Skip to content

Commit fe0fc88

Browse files
LiSedaLiSeda
committed
updates1
1 parent f652d10 commit fe0fc88

File tree

5 files changed

+1168
-154
lines changed

5 files changed

+1168
-154
lines changed

‎articles/azure-resource-manager/templates/deploy-to-management-group.md

Lines changed: 170 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,21 @@
11
---
22
title: Deploy resources to management group
3-
description: Describes how to deploy resources at the management group scope in an Azure Resource Manager template.
3+
description: Describes how to deploy resources at the management-group scope in an Azure Resource Manager template.
44
ms.topic: conceptual
5-
ms.date: 04/28/2025
5+
ms.date: 08/01/2025
66
ms.custom: devx-track-azurepowershell, devx-track-azurecli, devx-track-arm-template
77
---
88

9-
# Management group deployments with ARM templates
9+
# Management-group deployments with ARM templates
1010

11-
As your organization matures, you can deploy an Azure Resource Manager template (ARM template) to create resources at the management group level. For example, you may need to define and assign [policies](../../governance/policy/overview.md) or [Azure role-based access control (Azure RBAC)](../../role-based-access-control/overview.md) for a management group. With management group level templates, you can declaratively apply policies and assign roles at the management group level.
11+
As your organization matures, you can deploy an Azure Resource Manager template (ARM template) to create resources at the management-group level. For example, you might need to define and assign [policies](../../governance/policy/overview.md) or [Azure role-based access control (Azure RBAC)](../../role-based-access-control/overview.md) for a management group. With management-group-level templates, you can declaratively apply policies and assign roles at the management-group level.
1212

1313
> [!TIP]
14-
> We recommend [Bicep](../bicep/overview.md) because it offers the same capabilities as ARM templates and the syntax is easier to use. To learn more, see [management group deployments](../bicep/deploy-to-management-group.md).
14+
> [Bicep](../bicep/overview.md) is recommended since it offers the same capabilities as ARM templates, and the syntax is easier to use. To learn more, see [management-group deployments](../bicep/deploy-to-management-group.md).
1515
1616
## Supported resources
1717

18-
Not all resource types can be deployed to the management group level. This section lists which resource types are supported.
18+
Not all resource types can be deployed to the management-group level. This section lists which resource types are supported.
1919

2020
For Azure Blueprints, use:
2121

@@ -49,11 +49,11 @@ For managing your resources, use:
4949
* [diagnosticSettings](/azure/templates/microsoft.insights/diagnosticsettings)
5050
* [tags](/azure/templates/microsoft.resources/tags)
5151

52-
Management groups are tenant-level resources. However, you can create management groups in a management group deployment by setting the scope of the new management group to the tenant. See [Management group](#management-group).
52+
Management groups are tenant-level resources. However, you can create management groups in a management-group deployment by setting the scope of the new management group to the tenant. See [Management group](#management-group).
5353

5454
## Schema
5555

56-
The schema you use for management group deployments is different than the schema for resource group deployments.
56+
The schema you use for management-group deployments is different than the schema for resource group deployments.
5757

5858
For templates, use:
5959

@@ -75,7 +75,7 @@ The schema for a parameter file is the same for all deployment scopes. For param
7575

7676
## Deployment commands
7777

78-
To deploy to a management group, use the management group deployment commands.
78+
To deploy to a management group, use the management-group deployment commands.
7979

8080
# [Azure CLI](#tab/azure-cli)
8181

@@ -114,11 +114,11 @@ For more detailed information about deployment commands and options for deployin
114114

115115
## Deployment location and name
116116

117-
For management group level deployments, you must provide a location for the deployment. The location of the deployment is separate from the location of the resources you deploy. The deployment location specifies where to store deployment data. [Subscription](deploy-to-subscription.md) and [tenant](deploy-to-tenant.md) deployments also require a location. For [resource group](deploy-to-resource-group.md) deployments, the location of the resource group is used to store the deployment data.
117+
For management-group-level deployments, you must provide a location for the deployment. The location of the deployment is separate from the location of the resources you deploy. The deployment location specifies where to store deployment data. [Subscription](deploy-to-subscription.md) and [tenant](deploy-to-tenant.md) deployments also require a location. For [resource group](deploy-to-resource-group.md) deployments, the location of the resource group is used to store the deployment data.
118118

119119
You can provide a name for the deployment, or use the default deployment name. The default name is the name of the template file. For example, deploying a template named _azuredeploy.json_ creates a default deployment name of **azuredeploy**.
120120

121-
For each deployment name, the location is immutable. You can't create a deployment in one location when there's an existing deployment with the same name in a different location. For example, if you create a management group deployment with the name **deployment1** in **centralus**, you can't later create another deployment with the name **deployment1** but a location of **westus**. If you get the error code `InvalidDeploymentLocation`, either use a different name or the same location as the previous deployment for that name.
121+
For each deployment name, the location is immutable. You can't create a deployment in one location when there's an existing deployment with the same name in a different location. For example, if you create a management-group deployment with the name **deployment1** in **centralus**, you can't later create another deployment with the name **deployment1** but a location of **westus**. If you get the error code `InvalidDeploymentLocation`, use a different name or the same location as the previous deployment for that name.
122122

123123
## Deployment scopes
124124

@@ -132,59 +132,197 @@ When deploying to a management group, you can deploy resources to:
132132

133133
[!INCLUDE [Scope transitions](../../../includes/resource-manager-scope-transition.md)]
134134

135-
An [extension resource](scope-extension-resources.md) can be scoped to a target that is different than the deployment target.
135+
An [extension resource](scope-extension-resources.md) can be scoped to a target that's different from the deployment target.
136136

137137
The user deploying the template must have access to the specified scope.
138138

139139
This section shows how to specify different scopes. You can combine these different scopes in a single template.
140140

141141
### Scope to target management group
142142

143-
Resources defined within the resources section of the template are applied to the management group from the deployment command.
143+
Resources defined within the **resources** section of the template are applied to the management group from the deployment command:
144144

145-
:::code language="json" source="~/resourcemanager-templates/azure-resource-manager/scope/default-mg.json" highlight="5":::
145+
```json
146+
{
147+
"$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
148+
"contentVersion": "1.0.0.0",
149+
"resources": [
150+
management-group-resources-default
151+
],
152+
"outputs": {}
153+
}
154+
```
146155

147156
### Scope to another management group
148157

149-
To target another management group, add a nested deployment and specify the `scope` property. Set the `scope` property to a value in the format `Microsoft.Management/managementGroups/<mg-name>`.
158+
To target another management group, add a nested deployment and specify the `scope` property. Set the `scope` property to a value in the `Microsoft.Management/managementGroups/<mg-name>` format.
150159

151-
:::code language="json" source="~/resourcemanager-templates/azure-resource-manager/scope/scope-mg.json" highlight="10,17,18,22":::
160+
```json
161+
{
162+
"$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
163+
"contentVersion": "1.0.0.0",
164+
"parameters": {
165+
"mgName": {
166+
"type": "string"
167+
}
168+
},
169+
"variables": {
170+
"mgId": "[format('Microsoft.Management/managementGroups/{0}', parameters('mgName'))]"
171+
},
172+
"resources": [
173+
{
174+
"type": "Microsoft.Resources/deployments",
175+
"apiVersion": "2022-09-01",
176+
"name": "nestedDeployment",
177+
"scope": "[variables('mgId')]",
178+
"location": "eastus",
179+
"properties": {
180+
"mode": "Incremental",
181+
"template": {
182+
management-group-resources-non-default
183+
}
184+
}
185+
}
186+
],
187+
"outputs": {}
188+
}
189+
```
152190

153191
### Scope to subscription
154192

155193
You can also target subscriptions within a management group. The user deploying the template must have access to the specified scope.
156194

157-
To target a subscription within the management group, use a nested deployment and the `subscriptionId` property.
195+
To target a subscription within the management group, use a nested deployment and the `subscriptionId` property:
158196

159-
:::code language="json" source="~/resourcemanager-templates/azure-resource-manager/scope/mg-to-subscription.json" highlight="9,10,18":::
197+
```json
198+
{
199+
"$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
200+
"contentVersion": "1.0.0.0",
201+
"resources": [
202+
{
203+
"type": "Microsoft.Resources/deployments",
204+
"apiVersion": "2022-09-01",
205+
"name": "nestedSub",
206+
"location": "westus2",
207+
"subscriptionId": "00000000-0000-0000-0000-000000000000",
208+
"properties": {
209+
"mode": "Incremental",
210+
"template": {
211+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
212+
"contentVersion": "1.0.0.0",
213+
"resources": [
214+
{
215+
subscription-resources
216+
}
217+
]
218+
}
219+
}
220+
}
221+
]
222+
}
223+
```
160224

161225
### Scope to resource group
162226

163227
You can also target resource groups within the management group. The user deploying the template must have access to the specified scope.
164228

165-
To target a resource group within the management group, use a nested deployment. Set the `subscriptionId` and `resourceGroup` properties. Don't set a location for the nested deployment because it's deployed in the location of the resource group.
229+
To target a resource group within the management group, use a nested deployment. Set the `subscriptionId` and `resourceGroup` properties. Don't set a location for the nested deployment because it's deployed in the location of the resource group:
166230

167-
:::code language="json" source="~/resourcemanager-templates/azure-resource-manager/scope/mg-to-resource-group.json" highlight="9,10,18":::
231+
```json
232+
{
233+
"$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
234+
"contentVersion": "1.0.0.0",
235+
"resources": [
236+
{
237+
"type": "Microsoft.Resources/deployments",
238+
"apiVersion": "2022-09-01",
239+
"name": "nestedRGDeploy",
240+
"subscriptionId": "00000000-0000-0000-0000-000000000000",
241+
"resourceGroup": "demoResourceGroup",
242+
"properties": {
243+
"mode": "Incremental",
244+
"template": {
245+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
246+
"contentVersion": "1.0.0.0",
247+
"resources": [
248+
{
249+
resource-group-resources
250+
}
251+
]
252+
}
253+
}
254+
}
255+
]
256+
}
257+
```
168258

169-
To use a management group deployment for creating a resource group within a subscription and deploying a storage account to that resource group, see [Deploy to subscription and resource group](#deploy-to-subscription-and-resource-group).
259+
To use a management-group deployment for creating a resource group within a subscription and deploying a storage account to that resource group, see [Deploy to subscription and resource group](#deploy-to-subscription-and-resource-group).
170260

171261
### Scope to tenant
172262

173263
To create resources at the tenant, set the `scope` to `/`. The user deploying the template must have the [required access to deploy at the tenant](deploy-to-tenant.md#required-access).
174264

175-
To use a nested deployment, set `scope` and `location`.
265+
To use a nested deployment, set `scope` and `location`:
176266

177-
:::code language="json" source="~/resourcemanager-templates/azure-resource-manager/scope/management-group-to-tenant.json" highlight="9,10,14":::
267+
```json
268+
{
269+
"$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
270+
"contentVersion": "1.0.0.0",
271+
"resources": [
272+
{
273+
"type": "Microsoft.Resources/deployments",
274+
"apiVersion": "2022-09-01",
275+
"name": "nestedDeployment",
276+
"location": "centralus",
277+
"scope": "/",
278+
"properties": {
279+
"mode": "Incremental",
280+
"template": {
281+
tenant-resources
282+
}
283+
}
284+
}
285+
],
286+
"outputs": {}
287+
}
288+
```
178289

179-
Or, you can set the scope to `/` for some resource types, like management groups. Creating a new management group is described in the next section.
290+
Or, you can set the scope to `/` for some resource types like management groups. Creating a new management group is described in the next section.
180291

181292
## Management group
182293

183-
To create a management group in a management group deployment, you must set the scope to `/` for the management group.
294+
To create a management group in a management-group deployment, you must set the scope to `/` for the management group.
184295

185-
The following example creates a new management group in the root management group.
296+
The following example creates a new management group in the root management group:
186297

187-
:::code language="json" source="~/resourcemanager-templates/azure-resource-manager/scope/management-group-create-mg.json" highlight="12,15":::
298+
```json
299+
{
300+
"$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
301+
"contentVersion": "1.0.0.0",
302+
"parameters": {
303+
"mgName": {
304+
"type": "string",
305+
"defaultValue": "[concat('mg-', uniqueString(newGuid()))]"
306+
}
307+
},
308+
"resources": [
309+
{
310+
"type": "Microsoft.Management/managementGroups",
311+
"apiVersion": "2021-04-01",
312+
"name": "[parameters('mgName')]",
313+
"scope": "/",
314+
"location": "eastus",
315+
"properties": {}
316+
}
317+
],
318+
"outputs": {
319+
"output": {
320+
"type": "string",
321+
"value": "[parameters('mgName')]"
322+
}
323+
}
324+
}
325+
```
188326

189327
The next example creates a new management group in the management group specified as the parent. Notice that the scope is set to `/`.
190328

@@ -238,9 +376,9 @@ To deploy a template that moves an existing Azure subscription to a new manageme
238376

239377
## Azure Policy
240378

241-
Custom policy definitions that are deployed to the management group are extensions of the management group. To get the ID of a custom policy definition, use the [extensionResourceId()](template-functions-resource.md#extensionresourceid) function. Built-in policy definitions are tenant level resources. To get the ID of a built-in policy definition, use the [tenantResourceId()](template-functions-resource.md#tenantresourceid) function.
379+
Custom policy definitions that are deployed to the management group are extensions of the management group. To get the ID of a custom policy definition, use the [`extensionResourceId()`](template-functions-resource.md#extensionresourceid) function. Built-in policy definitions are tenant-level resources. To get the ID of a built-in policy definition, use the [`tenantResourceId()`](template-functions-resource.md#tenantresourceid) function.
242380

243-
The following example shows how to [define](../../governance/policy/concepts/definition-structure.md) a policy at the management group level, and assign it.
381+
The following example shows how to [define](../../governance/policy/concepts/definition-structure.md) a policy at the management-group level and assign it:
244382

245383
```json
246384
{
@@ -310,7 +448,7 @@ The following example shows how to [define](../../governance/policy/concepts/def
310448

311449
## Deploy to subscription and resource group
312450

313-
From a management group level deployment, you can target a subscription within the management group. The following example creates a resource group within a subscription and deploys a storage account to that resource group.
451+
From a management-group-level deployment, you can target a subscription within the management group. The following example creates a resource group within a subscription and deploys a storage account to that resource group:
314452

315453
```json
316454
{
@@ -393,5 +531,5 @@ From a management group level deployment, you can target a subscription within t
393531
## Next steps
394532

395533
* To learn about assigning roles, see [Assign Azure roles using Azure Resource Manager templates](../../role-based-access-control/role-assignments-template.md).
396-
* For an example of deploying workspace settings for Microsoft Defender for Cloud, see [deployASCwithWorkspaceSettings.json](https://github.com/krnese/AzureDeploy/blob/master/ARM/deployments/deployASCwithWorkspaceSettings.json).
397-
* You can also deploy templates at [subscription level](deploy-to-subscription.md) and [tenant level](deploy-to-tenant.md).
534+
* For an example of deploying workspace settings for Microsoft Defender for Cloud, see [_deployASCwithWorkspaceSettings.json_](https://github.com/krnese/AzureDeploy/blob/master/ARM/deployments/deployASCwithWorkspaceSettings.json).
535+
* You can also deploy templates at the [subscription level](deploy-to-subscription.md) and [tenant level](deploy-to-tenant.md).

0 commit comments

Comments
 (0)