Skip to content

Commit d2cbd3d

Browse files
mumianmumian
committed
Refresh the extension resource scope article
1 parent f64846c commit d2cbd3d

File tree

1 file changed

+162
-19
lines changed

1 file changed

+162
-19
lines changed

‎articles/azure-resource-manager/templates/scope-extension-resources.md

Lines changed: 162 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -2,40 +2,63 @@
22
title: Scope on extension resource types
33
description: Describes how to use the scope property when deploying extension resource types.
44
ms.topic: how-to
5-
ms.date: 04/28/2025
5+
ms.date: 07/15/2025
66
ms.custom: devx-track-azurepowershell, devx-track-azurecli
77
---
88

9-
# Setting scope for extension resources in ARM templates
9+
# How to set scope for extension resources in ARM templates
1010

11-
An extension resource is a resource that modifies another resource. For example, you can assign a role to a resource. The role assignment is an extension resource type.
11+
Learn how to use the `scope` property with extension resource types in Azure Resource Manager (ARM) templates. Extension resources let you modify or add capabilities to other resources, such as assigning a role or applying a lock.
1212

13-
For a full list of extension resource types, see [Resource types that extend capabilities of other resources](../management/extension-resource-types.md).
13+
Extension resources are a powerful way to manage permissions, policies, and other settings on Azure resources. For a full list, see [Resource types that extend capabilities of other resources](../management/extension-resource-types.md).
1414

15-
This article shows how to set the scope for an extension resource type when deployed with an Azure Resource Manager template (ARM template). It describes the scope property that is available for extension resources when applying to a resource.
15+
The `scope` property is only available to extension resource types. To specify a different scope for a resource type that isn't an extension type, use a nested or linked deployment. For more information, see:
1616

17-
> [!NOTE]
18-
> The scope property is only available to extension resource types. To specify a different scope for a resource type that isn't an extension type, use a nested or linked deployment. For more information, see [resource group deployments](deploy-to-resource-group.md), [subscription deployments](deploy-to-subscription.md), [management group deployments](deploy-to-management-group.md), and [tenant deployments](deploy-to-tenant.md).
17+
- [Resource group deployments](deploy-to-resource-group.md)
18+
- [Subscription deployments](deploy-to-subscription.md)
19+
- [Management group deployments](deploy-to-management-group.md)
20+
- [Tenant deployments](deploy-to-tenant.md)
1921

2022
## Apply at deployment scope
2123

22-
To apply an extension resource type at the target deployment scope, you add the resource to your template, as would with any resource type. The available scopes are [resource group](deploy-to-resource-group.md), [subscription](deploy-to-subscription.md), [management group](deploy-to-management-group.md), and [tenant](deploy-to-tenant.md). The deployment scope must support the resource type.
24+
To apply an extension resource type at the target deployment scope, you add the resource to your template, as would with any resource type. The available scopes are:
25+
26+
- Resource group
27+
- Subscription
28+
- Management group
29+
- Tenant
2330

2431
The following template deploys a lock.
2532

26-
:::code language="json" source="~/resourcemanager-templates/azure-resource-manager/scope/locktargetscope.json":::
33+
```json
34+
{
35+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
36+
"contentVersion": "1.0.0.0",
37+
"resources": [
38+
{
39+
"type": "Microsoft.Authorization/locks",
40+
"apiVersion": "2020-05-01",
41+
"name": "rgLock",
42+
"properties": {
43+
"level": "CanNotDelete",
44+
"notes": "Resource Group should not be deleted."
45+
}
46+
}
47+
]
48+
}
49+
```
2750

2851
When deployed to a resource group, it locks the resource group.
2952

30-
# [Azure CLI](#tab/azure-cli)
53+
### [Azure CLI](#tab/azure-cli)
3154

3255
```azurecli-interactive
3356
az deployment group create \
3457
--resource-group ExampleGroup \
3558
--template-uri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/azure-resource-manager/scope/locktargetscope.json"
3659
```
3760

38-
# [PowerShell](#tab/azure-powershell)
61+
### [PowerShell](#tab/azure-powershell)
3962

4063
```azurepowershell-interactive
4164
New-AzResourceGroupDeployment `
@@ -47,11 +70,59 @@ az deployment group create \
4770

4871
The next example assigns a role.
4972

50-
:::code language="json" source="~/resourcemanager-templates/azure-resource-manager/scope/roletargetscope.json":::
73+
```json
74+
{
75+
"$schema": "https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#",
76+
"contentVersion": "1.0.0.0",
77+
"parameters": {
78+
"principalId": {
79+
"type": "string",
80+
"metadata": {
81+
"description": "The principal to assign the role to"
82+
}
83+
},
84+
"builtInRoleType": {
85+
"type": "string",
86+
"allowedValues": [
87+
"Owner",
88+
"Contributor",
89+
"Reader"
90+
],
91+
"metadata": {
92+
"description": "Built-in role to assign"
93+
}
94+
},
95+
"roleNameGuid": {
96+
"type": "string",
97+
"metadata": {
98+
"description": "The role assignment name"
99+
}
100+
}
101+
},
102+
"variables": {
103+
"roleDefinitionIds": {
104+
"Owner": "[format('/subscriptions/{0}/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635', subscription().subscriptionId)]",
105+
"Contributor": "[format('/subscriptions/{0}/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c', subscription().subscriptionId)]",
106+
"Reader": "[format('/subscriptions/{0}/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7', subscription().subscriptionId)]"
107+
}
108+
},
109+
"resources": [
110+
{
111+
"type": "Microsoft.Authorization/roleAssignments",
112+
"apiVersion": "2022-04-01",
113+
"name": "[parameters('roleNameGuid')]",
114+
"properties": {
115+
"roleDefinitionId": "[variables('roleDefinitionIds')[parameters('builtInRoleType')]]",
116+
"principalId": "[parameters('principalId')]"
117+
}
118+
}
119+
]
120+
}
121+
```
51122

52123
When deployed to a subscription, it assigns the role to the subscription.
53124

54-
# [Azure CLI](#tab/azure-cli)
125+
### [Azure CLI](#tab/azure-cli)
55126

56127
```azurecli-interactive
57128
az deployment sub create \
@@ -60,7 +131,7 @@ az deployment sub create \
60131
--template-uri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/azure-resource-manager/scope/roletargetscope.json"
61132
```
62133

63-
# [PowerShell](#tab/azure-powershell)
134+
### [PowerShell](#tab/azure-powershell)
64135

65136
```azurepowershell-interactive
66137
New-AzSubscriptionDeployment `
@@ -77,12 +148,84 @@ To apply an extension resource to a resource, use the `scope` property. Set the
77148

78149
The following example creates a storage account and applies a role to it.
79150

80-
:::code language="json" source="~/resourcemanager-templates/azure-resource-manager/scope/storageandrole.json" highlight="56":::
151+
```json
152+
{
153+
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
154+
"contentVersion": "1.0.0.0",
155+
"parameters": {
156+
"principalId": {
157+
"type": "string",
158+
"metadata": {
159+
"description": "The principal to assign the role to"
160+
}
161+
},
162+
"builtInRoleType": {
163+
"type": "string",
164+
"allowedValues": [
165+
"Owner",
166+
"Contributor",
167+
"Reader"
168+
],
169+
"metadata": {
170+
"description": "Built-in role to assign"
171+
}
172+
},
173+
"roleNameGuid": {
174+
"type": "string",
175+
"defaultValue": "[newGuid()]",
176+
"metadata": {
177+
"description": "A new GUID used to identify the role assignment"
178+
}
179+
},
180+
"location": {
181+
"type": "string",
182+
"defaultValue": "[resourceGroup().location]",
183+
"metadata": {
184+
"description": "The location for the resources"
185+
}
186+
}
187+
},
188+
"variables": {
189+
"roleDefinitionIds": {
190+
"Owner": "[format('/subscriptions/{0}/providers/Microsoft.Authorization/roleDefinitions/8e3af657-a8ff-443c-a75c-2fe8c4bcb635', subscription().subscriptionId)]",
191+
"Contributor": "[format('/subscriptions/{0}/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c', subscription().subscriptionId)]",
192+
"Reader": "[format('/subscriptions/{0}/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7', subscription().subscriptionId)]"
193+
},
194+
"storageName": "[format('storage{0}', uniqueString(resourceGroup().id))]"
195+
},
196+
"resources": [
197+
{
198+
"type": "Microsoft.Storage/storageAccounts",
199+
"apiVersion": "2025-01-01",
200+
"name": "[variables('storageName')]",
201+
"location": "[parameters('location')]",
202+
"sku": {
203+
"name": "Standard_LRS"
204+
},
205+
"kind": "Storage",
206+
"properties": {}
207+
},
208+
{
209+
"type": "Microsoft.Authorization/roleAssignments",
210+
"apiVersion": "2022-04-01",
211+
"scope": "[format('Microsoft.Storage/storageAccounts/{0}', variables('storageName'))]",
212+
"name": "[parameters('roleNameGuid')]",
213+
"properties": {
214+
"roleDefinitionId": "[variables('roleDefinitionIds')[parameters('builtInRoleType')]]",
215+
"principalId": "[parameters('principalId')]"
216+
},
217+
"dependsOn": [
218+
"[resourceId('Microsoft.Storage/storageAccounts', variables('storageName'))]"
219+
]
220+
}
221+
]
222+
}
223+
```
81224

82-
The resourceGroup and subscription properties are only allowed on nested or linked deployments. These properties are not allowed on individual resources. Use nested or linked deployments if you want to deploy an extension resource with the scope set to a resource in a different resource group.
225+
The resourceGroup and subscription properties are only allowed on nested or linked deployments. These properties aren't allowed on individual resources. Use nested or linked deployments if you want to deploy an extension resource with the scope set to a resource in a different resource group.
83226

84227
## Next steps
85228

86-
* To understand how to define parameters in your template, see [Understand the structure and syntax of ARM templates](./syntax.md).
87-
* For tips on resolving common deployment errors, see [Troubleshoot common Azure deployment errors with Azure Resource Manager](common-deployment-errors.md).
88-
* For information about deploying a template that requires a SAS token, see [Deploy private ARM template with SAS token](secure-template-with-sas-token.md).
229+
- To understand how to define parameters in your template, see [Understand the structure and syntax of ARM templates](./syntax.md).
230+
- For tips on resolving common deployment errors, see [Troubleshoot common Azure deployment errors with Azure Resource Manager](common-deployment-errors.md).
231+
- For information about deploying a template that requires a SAS token, see [Deploy private ARM template with SAS token](secure-template-with-sas-token.md).

0 commit comments

Comments
 (0)