add more information for deployment scopes

Author: mumian

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,21 @@ 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 does not 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)
+
+// TODO add a note about exceptions to the "same resoure group rule" in the management-group equivalent of this doc - we permit tenant-level resource PUTs from mg-level deployments
 
 ### Scope to management group
 
@@ -128,7 +132,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 does not 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
 

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 does not 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](#score-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 does not 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