Task 01: Configure Management Groups
DOCUMENT CATEGORY: Runbook
SCOPE: Full CAF/WAF management group hierarchy
PURPOSE: Deploy complete CAF-aligned management group structure
MASTER REFERENCE: Azure Landing Zones — Enterprise-Scale Architecture
Status: Active
Overview
Create the complete management group hierarchy following the Azure Landing Zone conceptual architecture. This establishes the enterprise-grade governance structure for multi-subscription Azure Local environments, with hierarchical policy inheritance and RBAC boundaries.
The management group hierarchy is the backbone of Azure governance — every policy, role assignment, and budget you define at the MG level cascades to all subscriptions and resources beneath it. Getting this right from the start means your Azure Local clusters inherit consistent security, compliance, and operational controls automatically.
What This Accomplishes
- Governance structure — complete CAF Enterprise-Scale management group hierarchy
- Policy inheritance — hierarchical policy and RBAC inheritance from your organization root down through platform and landing zone scopes
- Landing zone organization — structured landing zones for corporate (Azure Local) and online workloads
- Lifecycle management — sandbox and decommissioned MGs for experimentation and teardown
Every Azure tenant has a built-in Tenant Root Group that cannot be renamed or deleted. In this task, you create your organization root management group (e.g., cmp-iic-root) directly beneath it, then build the full hierarchy under that. This keeps your organization's structure cleanly separated from the tenant default.
Management Group Naming
Management groups have two identifiers:
| Property | Description | Can Change? |
|---|---|---|
ID (GroupName) | Used in ARM/Bicep, CLI, and policy assignments | No — immutable once created |
| Display Name | Shown in Azure Portal | Yes — editable anytime |
Target Hierarchy (IIC Example)
Tenant Root Group
└── cmp-iic-root # already exists
├── cmp-platform-iic # Platform Services
│ ├── cmp-platform-identity-iic # Identity
│ ├── cmp-platform-management-iic # Management
│ └── cmp-platform-connectivity-iic # Connectivity
├── cmp-landing-zones-iic # Landing Zones
│ ├── cmp-lz-corp-iic # Corp Landing Zone
│ └── cmp-lz-online-iic # Online Landing Zone
├── cmp-sandbox-iic # Sandbox
└── cmp-decommissioned-iic # Decommissioned
Complete Hierarchy Table
| Level | Display Name | MG ID (IIC) | Config Path |
|---|---|---|---|
| 1 | IIC Root | cmp-iic-root | landing_zone.management_groups[].parent |
| 2 | Platform | cmp-platform-iic | landing_zone.management_groups[].name |
| 3 | Platform — Identity | cmp-platform-identity-iic | landing_zone.management_groups[].name |
| 3 | Platform — Management | cmp-platform-management-iic | landing_zone.management_groups[].name |
| 3 | Platform — Connectivity | cmp-platform-connectivity-iic | landing_zone.management_groups[].name |
| 2 | Landing Zones | cmp-landing-zones-iic | landing_zone.management_groups[].name |
| 3 | Corp Landing Zone | cmp-lz-corp-iic | landing_zone.management_groups[].name |
| 3 | Online Landing Zone | cmp-lz-online-iic | landing_zone.management_groups[].name |
| 2 | Sandbox | cmp-sandbox-iic | landing_zone.management_groups[].name |
| 2 | Decommissioned | cmp-decommissioned-iic | landing_zone.management_groups[].name |
Prerequisites
- Tenant access — you must have Owner or User Access Administrator role at the tenant root management group scope (see Elevate access to manage all Azure subscriptions)
- Permissions — Management Group Contributor (or Owner) at the scope where you'll create the hierarchy
- Authenticated Azure session — see Authentication
infrastructure.yml— configured with the full management group hierarchy names and display names
Values from infrastructure.yml
The script reads these keys from infrastructure.yml (schema 5). Each key, with its type, default and example, is in the variables reference.
Deploy-ManagementGroups.ps1:
azure.tenant_id the tenant the sign-in must belong to
landing_zone.management_groups[].name the management group id
landing_zone.management_groups[].display_name the display name (default: the name)
landing_zone.management_groups[].parent the name of the parent entry; empty for the tenant root
Set-ManagementGroupDisplayNames.ps1:
azure.tenant_id the tenant the sign-in must belong to
landing_zone.management_groups[].name the management group id (the group must already exist)
landing_zone.management_groups[].display_name the display name it must have
An entry of landing_zone.management_groups that is not a map stops Set-ManagementGroupDisplayNames.ps1 (and its Azure CLI twin) with exit 2.
Execution Options
- Azure Portal
- Orchestrated Script
- Azure CLI
Azure Portal
When to use: Single deployment, prefer visual interface
Procedure
- Navigate to Management Groups:
- In Azure Portal, search for Management groups
- Locate the root management group (
landing_zone.management_groups[].parent)
- Create Platform Management Groups:
- Select root MG → + Add management group
- Create the platform container:
| Field | Value | Config Path |
|---|---|---|
| MG ID | cmp-platform-iic | landing_zone.management_groups[].name |
| Display Name | Platform | landing_zone.management_groups[].display_name |
- Select the platform MG → + Add management group for each child:
| MG ID | Display Name | Config Path |
|---|---|---|
cmp-platform-identity-iic | Platform — Identity | landing_zone.management_groups[] |
cmp-platform-management-iic | Platform — Management | landing_zone.management_groups[] |
cmp-platform-connectivity-iic | Platform — Connectivity | landing_zone.management_groups[] |
- Create Landing Zone Management Groups:
- Select root MG → + Add management group
- Create the landing zones container:
| Field | Value | Config Path |
|---|---|---|
| MG ID | cmp-landing-zones-iic | landing_zone.management_groups[].name |
| Display Name | Landing Zones | landing_zone.management_groups[].display_name |
- Select the landing zones MG → + Add management group for each child:
| MG ID | Display Name | Config Path |
|---|---|---|
cmp-lz-corp-iic | Corp Landing Zone | landing_zone.management_groups[] |
cmp-lz-online-iic | Online Landing Zone | landing_zone.management_groups[] |
- Create Auxiliary Management Groups:
- Select root MG → + Add management group for each:
| MG ID | Display Name | Config Path |
|---|---|---|
cmp-sandbox-iic | Sandbox | landing_zone.management_groups[] |
cmp-decommissioned-iic | Decommissioned | landing_zone.management_groups[] |
Validation
- Platform hierarchy complete (platform + identity, management, connectivity)
- Landing zones hierarchy complete (landing-zones + corp, online)
- Sandbox and Decommissioned MGs created under root
- All IDs and display names match
infrastructure.yml
Links
PowerShell
When to use: Run the task from a management workstation or a pipeline. The script reads
infrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/02-azure-foundation/phase-01-landing-zones/full-deployment/task-01-configure-management-groups/powershell/Deploy-ManagementGroups.ps1 | Creates the Azure management group hierarchy that landing_zone.management_groups of infrastructure.yml lists. Supports -WhatIf. |
scripts/deploy/02-azure-foundation/phase-01-landing-zones/full-deployment/task-01-configure-management-groups/powershell/Set-ManagementGroupDisplayNames.ps1 | Renames existing management groups: sets the display name infrastructure.yml gives each one. Supports -WhatIf. |
Requires: PowerShell 7.
Run
./Deploy-ManagementGroups.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./Set-ManagementGroupDisplayNames.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
Azure CLI
When to use: Run the task from a host that has the Azure CLI and not the Az PowerShell modules. The script is PowerShell 7 that calls
az; it readsinfrastructure.ymland carries no values of its own.
Script
| Script | What it does |
|---|---|
scripts/deploy/02-azure-foundation/phase-01-landing-zones/full-deployment/task-01-configure-management-groups/azurecli/Deploy-ManagementGroups.azcli.ps1 | Creates the Azure management group hierarchy that landing_zone.management_groups of infrastructure.yml lists, with the Azure CLI. Supports -WhatIf. |
scripts/deploy/02-azure-foundation/phase-01-landing-zones/full-deployment/task-01-configure-management-groups/azurecli/Set-ManagementGroupDisplayNames.azcli.ps1 | Renames existing management groups with the Azure CLI: sets the display name infrastructure.yml gives each one. Supports -WhatIf. |
Requires: PowerShell 7 and the Azure CLI, signed in with az login --tenant <azure.tenant_id>.
Azure side only. Both scripts are idempotent. A group that exists is left alone: a different display name or parent is reported and not changed. The id of a management group can never change, only its display name. You need Management Group Contributor on the tenant root group (or on the parent group).
Run
./Deploy-ManagementGroups.azcli.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./Deploy-ManagementGroups.azcli.ps1 -InfrastructureFile ./infrastructure.yml
./Set-ManagementGroupDisplayNames.azcli.ps1 -InfrastructureFile ./infrastructure.yml -WhatIf
./Set-ManagementGroupDisplayNames.azcli.ps1 -InfrastructureFile ./infrastructure.yml
Troubleshooting
| Issue | Symptom | Resolution |
|---|---|---|
| Permission denied | AuthorizationFailed | Verify Management Group Contributor or Owner role on the root MG |
| Duplicate ID | ManagementGroupAlreadyExists | The MG already exists — verify it's under the correct parent and move on |
| Parent not found | ParentManagementGroupNotFound | Create parent MGs first (platform before platform children, etc.) |
| Hierarchy depth exceeded | HierarchyDepthExceeded | Azure limits MG depth to 6 levels — this hierarchy uses 3, well within limits |
Next Steps
Proceed to Task 02: Create Subscriptions
References
- Azure Landing Zones — Enterprise-Scale Architecture
- Management Groups Overview
- Create Management Groups (Portal)
- Elevate Access to Manage All Azure Subscriptions
- CAF Ready Methodology
Alternatives
The procedures in this task use the methods shown in the tabs above. The toolkit is PowerShell 7 only and has no Bash scripts. A few tasks that act on Azure also have an Azure CLI script written in PowerShell. The script status page of the toolkit lists which task has which script.
Navigation
| Previous | Up | Next |
|---|---|---|
| Full Deployment Overview | Full Deployment Overview | Task 02 — Create Subscriptions |
Version Control
- Created: 2026-01-15 by Hybrid Cloud Solutions
- Last Updated: 2026-03-19 by Hybrid Cloud Solutions
- Version: 3.0.0
Version Control
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0.0 | 2025-03-25 | Azure Local Cloud | Initial release |