Merge pull request #294431 from mumian/0206-deployment-scope

add more information for deployment scopes

Author: prmerger-automator[bot]

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

@@ -3,14 +3,14 @@ title: Use Bicep to deploy resources to management group
 description: Describes how to create a Bicep file that deploys resources at the management group scope.
 ms.topic: how-to
 ms.custom: devx-track-bicep
-ms.date: 09/26/2024
+ms.date: 02/10/2025
 ---
 
 # Management group deployments with Bicep files
 
 This article describes how to set scope with Bicep when deploying to a management group.
 
-As your organization matures, you can deploy a Bicep file 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.
+As your organization matures, you can deploy a Bicep file 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. For more information, see [Understand scope](../management/overview.md#understand-scope).
 
 ### Training resources
 
@@ -108,17 +108,19 @@ For each deployment name, the location is immutable. You can't create a deployme
 
 ## Deployment scopes
 
-When deploying to a management group, you can deploy resources to:
+In a Bicep file, all resources declared with the [`resource`](./resource-declaration.md) keyword must be deployed at the same scope as the deployment. For a management group deployment, this means all `resource` declarations in the Bicep file must be deployed to the same management group or as a child or extension resource of a resource in the same management group as the deployment.  
 
-* the target management group from the operation
-* another management group in the tenant
-* subscriptions in the management group
-* resource groups in the management group
-* the tenant for the resource group
+However, this restriction doesn't apply to [`existing`](./existing-resource.md) resources. You can reference existing resources at a different scope than the deployment.  
 
-An [extension resource](scope-extension-resources.md) can be scoped to a target that is different than the deployment target.
+To deploy resources at multiple scopes within a single deployment, use [modules](./modules.md). Deploying a module triggers a "nested deployment," allowing you to target different scopes. The user deploying the parent Bicep file must have the necessary permissions to initiate deployments at those scopes.
 
-The user deploying the template must have access to the specified scope.
+You can deploy a Bicep module from within a management-group scope Bicep file at the following scopes:
+
+* [The same management group](#scope-to-management-group)
+* [Other management groups](#scope-to-management-group)
+* [The subscription](#scope-to-subscription)
+* [The resource group](#scope-to-resource-group)
+* [The tenant](#scope-to-tenant)
 
 ### Scope to management group
 
@@ -128,7 +130,7 @@ To deploy resources to the target management group, add those resources with the
 targetScope = 'managementGroup'
 
 // policy definition created in the management group
-resource policyDefinition 'Microsoft.Authorization/policyDefinitions@2023-04-01' = {
+resource policyDefinition 'Microsoft.Authorization/policyDefinitions@2025-01-01' = {
   ...
 }
 ```

articles/azure-resource-manager/bicep/deploy-to-resource-group.md

@@ -3,12 +3,12 @@ title: Use Bicep to deploy resources to resource groups
 description: Describes how to deploy resources in a Bicep file. It shows how to target more than one resource group.
 ms.topic: how-to
 ms.custom: devx-track-bicep
-ms.date: 09/26/2024
+ms.date: 02/10/2025
 ---
 
 # Resource group deployments with Bicep files
 
-This article describes how to set scope with Bicep when deploying to a resource group.
+This article describes how to set scope with Bicep when deploying to a resource group. For more information, see [Understand scope](../management/overview.md#understand-scope).
 
 ## Supported resources
 
@@ -62,18 +62,19 @@ For more detailed information about deployment commands and options for deployin
 
 ## Deployment scopes
 
-When deploying to a resource group, you can deploy resources to:
+In a Bicep file, all resources declared with the [`resource`](./resource-declaration.md) keyword must be deployed at the same scope as the deployment. For a resource group deployment, this means all `resource` declarations in the Bicep file must be deployed to the same resource group or as a child or extension resource of a resource in the same resource group as the deployment.  
 
-* the target resource group for the deployment operation
-* other resource groups in the same subscription or other subscriptions
-* any subscription in the tenant
-* the tenant for the resource group
+However, this restriction doesn't apply to [`existing`](./existing-resource.md) resources. You can reference existing resources at a different scope than the deployment.  
 
-An [extension resource](scope-extension-resources.md) can be scoped to a target that is different than the deployment target.
+To deploy resources at multiple scopes within a single deployment, use [modules](./modules.md). Deploying a module triggers a "nested deployment," allowing you to target different scopes. The user deploying the parent Bicep file must have the necessary permissions to initiate deployments at those scopes.
 
-The user deploying the template must have access to the specified scope.
+You can deploy a resource from within a resource-group scope Bicep file at the following scopes:
 
-This section shows how to specify different scopes. You can combine these different scopes in a single template.
+* [The same resource group](#scope-to-target-resource-group)
+* [Other resource groups in the same subscription](#scope-to-different-resource-group)
+* [Other resource groups in other subscriptions](#scope-to-different-resource-group)
+* [The subscription](#scope-to-subscription)
+* [The tenant](#scope-to-tenant)
 
 ### Scope to target resource group
 
@@ -228,7 +229,7 @@ output storageEndpoint object = stg.properties.primaryEndpoints
 You can deploy to more than one resource group in a single Bicep file.
 
 > [!NOTE]
-> You can deploy to **800 resource groups** in a single deployment. Typically, this limitation means you can deploy to one resource group specified for the parent template, and up to 799 resource groups in nested or linked deployments. However, if your parent template contains only nested or linked templates and does not itself deploy any resources, then you can include up to 800 resource groups in nested or linked deployments.
+> You can deploy to **800 resource groups** in a single deployment. Typically, this limitation means you can deploy to one resource group specified for the parent template, and up to 799 resource groups in nested or linked deployments. However, if your parent template contains only nested or linked templates and doesn't itself deploy any resources, then you can include up to 800 resource groups in nested or linked deployments.
 
 The following example deploys two storage accounts. The first storage account is deployed to the resource group specified in the deployment operation. The second storage account is deployed to the resource group specified in the `secondResourceGroup` and `secondSubscriptionID` parameters:
 

articles/azure-resource-manager/bicep/deploy-to-subscription.md

@@ -3,14 +3,14 @@ title: Use Bicep to deploy resources to subscription
 description: Describes how to create a Bicep file that deploys resources to the Azure subscription scope.
 ms.topic: how-to
 ms.custom: devx-track-bicep
-ms.date: 09/26/2024
+ms.date: 02/10/2025
 ---
 
 # Subscription deployments with Bicep files
 
 To simplify the management of resources, you can deploy resources at the level of your Azure subscription. For example, you can deploy [policies](../../governance/policy/overview.md) and [Azure role-based access control (Azure RBAC)](../../role-based-access-control/overview.md) to your subscription, which applies them across your subscription.
 
-This article describes how to set the deployment scope to a subscription in a Bicep file.
+This article describes how to set the deployment scope to a subscription in a Bicep file. For more information, see [Understand scope](../management/overview.md#understand-scope).
 
 > [!NOTE]
 > You can deploy to 800 different resource groups in a subscription level deployment.
@@ -146,16 +146,18 @@ For each deployment name, the location is immutable. You can't create a deployme
 
 ## Deployment scopes
 
-When deploying to a subscription, you can deploy resources to:
+In a Bicep file, all resources declared with the [`resource`](./resource-declaration.md) keyword must be deployed at the same scope as the deployment. For a subscription deployment, this means all `resource` declarations in the Bicep file must be deployed to the same subscription or as a child or extension resource of a resource in the same subscription as the deployment.  
 
-* the target subscription from the operation
-* any subscription in the tenant
-* resource groups within the subscription or other subscriptions
-* the tenant for the subscription
+However, this restriction doesn't apply to [`existing`](./existing-resource.md) resources. You can reference existing resources at a different scope than the deployment.  
 
-An [extension resource](scope-extension-resources.md) can be scoped to a target that is different than the deployment target.
+To deploy resources at multiple scopes within a single deployment, use [modules](./modules.md). Deploying a module triggers a "nested deployment," allowing you to target different scopes. The user deploying the parent Bicep file must have the necessary permissions to initiate deployments at those scopes.
 
-The user deploying the template must have access to the specified scope.
+You can deploy a resource from within a subscription scope Bicep file at the following scopes:
+
+* [The same subscription](#scope-to-subscription)
+* [Other subscriptions](#scope-to-subscription)
+* [The resource group](#scope-to-resource-group)
+* [The tenant](#scope-to-tenant)
 
 ### Scope to subscription
 
@@ -165,7 +167,7 @@ To deploy resources to the target subscription, add those resources with the `re
 targetScope = 'subscription'
 
 // resource group created in target subscription
-resource exampleResource 'Microsoft.Resources/resourceGroups@2024-03-01' = {
+resource exampleResource 'Microsoft.Resources/resourceGroups@2024-11-01' = {
   ...
 }
 ```

articles/azure-resource-manager/bicep/deploy-to-tenant.md

@@ -3,7 +3,7 @@ title: Use Bicep to deploy resources to tenant
 description: Describes how to deploy resources at the tenant scope in a Bicep file.
 ms.topic: how-to
 ms.custom: devx-track-bicep
-ms.date: 09/26/2024
+ms.date: 02/10/2025
 ---
 
 # Tenant deployments with Bicep file
@@ -120,18 +120,18 @@ For each deployment name, the location is immutable. You can't create a deployme
 
 ## Deployment scopes
 
-When deploying to a tenant, you can deploy resources to:
+In a Bicep file, all resources declared with the [`resource`](./resource-declaration.md) keyword must be deployed at the same scope as the deployment. For a tenant deployment, this means all `resource` declarations in the Bicep file must be deployed to the same tenant or as a child or extension resource of a resource in the same tenant as the deployment.  
 
-* the tenant
-* management groups within the tenant
-* subscriptions
-* resource groups
+However, this restriction doesn't apply to [`existing`](./existing-resource.md) resources. You can reference existing resources at a different scope than the deployment.  
 
-An [extension resource](scope-extension-resources.md) can be scoped to a target that is different than the deployment target.
+To deploy resources at multiple scopes within a single deployment, use [modules](./modules.md). Deploying a module triggers a "nested deployment," allowing you to target different scopes. The user deploying the parent Bicep file must have the necessary permissions to initiate deployments at those scopes.
 
-The user deploying the template must have access to the specified scope.
+You can deploy a resource from within a tenant scope Bicep file at the following scopes:
 
-This section shows how to specify different scopes. You can combine these different scopes in a single template.
+* [The tenant](#scope-to-tenant)
+* [The management group](#scope-to-management-group)
+* [The subscription](#scope-to-subscription)
+* [The resource group](#scope-to-resource-group)
 
 ### Scope to tenant