Merge pull request #276096 from mumian/0522-stack-outofsync

document bypassoutofsyncerror

Author: prmerger-automator[bot]

articles/azure-resource-manager/bicep/deployment-stacks.md

@@ -8,13 +8,13 @@ ms.date: 05/28/2024
 
 # Deployment stacks
 
-An Azure deployment stack is a type of Azure resource that enables the management of a group of Azure resources as an atomic unit. When a Bicep file or an ARM JSON template is submitted to a deployment stack, it defines the resources that are managed by the stack. If a resource that was previously included in the template is removed, it will either be detached or deleted based on the specified _actionOnUnmanage_ behavior of the deployment stack. Similar to other Azure resources, access to the deployment stack can be restricted using Azure role-based access control (Azure RBAC). 
+An Azure deployment stack is a resource that enables you to manage a group of Azure resources as a single, cohesive unit. When you submit a Bicep file or an ARM JSON template to a deployment stack, it defines the resources that the stack manage. If a resource previously included in the template is removed, it will either be detached or deleted based on the specified _actionOnUnmanage_ behavior of the deployment stack. Access to the deployment stack can be restricted using Azure role-based access control (Azure RBAC), similar to other Azure resources.
 
 To create and update a deployment stack, you can utilize Azure CLI, Azure PowerShell, or the Azure portal along with Bicep files. These Bicep files are transpiled into ARM JSON templates, which are then deployed as a deployment object by the stack. The deployment stack offers additional capabilities beyond the [familiar deployment resources](./deploy-cli.md), serving as a superset of those capabilities.
 
 `Microsoft.Resources/deploymentStacks` is the resource type for deployment stacks. It consists of a main template that can perform 1-to-many updates across scopes to the resources it describes, and block any unwanted changes to those resources.
 
-When planning your deployment and determining which resource groups should be part of the same stack, it's important to consider the management lifecycle of those resources, which includes creation, updating, and deletion. For instance, suppose you need to provision some test VMs for various application teams across different resource group scopes. In this case, a deployment stack can be utilized to  create these test environments and update the test VM configurations through subsequent updates to the deployment stack. After completing the project, it may be necessary to remove or delete any resources that were created, such as the test VMs. By utilizing a deployment stack, the managed resources can be easily removed by specifying the appropriate delete flag. This streamlined approach saves time during environment cleanup, as it involves a single update to the stack resource rather than individually modifying or removing each test VM across various resource group scopes.
+When planning your deployment and determining which resource groups should be part of the same stack, it's important to consider the management lifecycle of those resources, which includes creation, updating, and deletion. For instance, suppose you need to provision some test virtual machines(VM) for various application teams across different resource group scopes. In this case, a deployment stack can be utilized to  create these test environments and update the test VM configurations through subsequent updates to the deployment stack. After completing the project, it may be necessary to remove or delete any resources that were created, such as the test VMs. By utilizing a deployment stack, the managed resources can be easily removed by specifying the appropriate delete flag. This streamlined approach saves time during environment cleanup, as it involves a single update to the stack resource rather than individually modifying or removing each test VM across various resource group scopes.
 
 Deployment stacks requires Azure PowerShell [version 12.0.0 or later](/powershell/azure/install-az-ps) or Azure CLI [version 2.61.0 or later](/cli/azure/install-azure-cli).
 
@@ -24,24 +24,24 @@ To create your first deployment stack, work through [Quickstart: create deployme
 
 Deployment stacks provide the following benefits:
 
-- Simplified provisioning and management of resources across different scopes as a cohesive entity.
-- Preventing undesired modifications to managed resources through [deny settings](#protect-managed-resources-against-deletion).
-- Efficient environment cleanup by employing delete flags during deployment stack updates.
-- Utilizing standard templates such as Bicep, ARM templates, or Template specs for your deployment stacks.
+- Streamlined provisioning and management of resources across different scopes as a unified entity.
+- Prevention of undesired modifications to managed resources via [deny settings](#protect-managed-resources-against-deletion).
+- Efficient environment cleanup using delete flags during deployment stack updates.
+- Use of standard templates such as Bicep, ARM templates, or Template specs for your deployment stacks.
 
 ### Known limitations
 
-- Implicitly created resources aren't managed by the stack. Therefore, no deny assignments or cleanup is possible.
-- Deny assignments don't support tags.
-- Deny assignments are not supported at the management group scope. However, they are supported in a management group stack if the deployment is pointed at the subscription scope.
-- Deployment stacks cannot delete Key vault secrets. If you're removing key vault secrets from a template, make sure to also execute the deployment stack update/delete command with detach mode.
+- Implicitly created resources aren't managed by the stack. Therefore, no deny-assignments or cleanup is possible.
+- Deny-assignments don't support tags.
+- Deny-assignments aren't supported at the management group scope. However, they're supported in a management group stack if the deployment is pointed at the subscription scope.
+- Deployment stacks can't delete Key vault secrets. If you're removing key vault secrets from a template, make sure to also execute the deployment stack update/delete command with detach mode.
 
 ### Known issues
 
-- Deleting resource groups currently bypasses deny assignments. When creating a deployment stack in the resource group scope, the Bicep file doesn't contain the definition for the resource group. Despite the deny assignment setting, it's possible to delete the resource group and its contained stack. However, if a [lock](../management/lock-resources.md) is active on any resource within the group, the delete operation will fail.
-- The [What-if](./deploy-what-if.md) support is not yet available.
+- Deleting resource groups currently bypasses deny-assignments. When creating a deployment stack in the resource group scope, the Bicep file doesn't contain the definition for the resource group. Despite the deny-assignment setting, it's possible to delete the resource group and its contained stack. However, if a [lock](../management/lock-resources.md) is active on any resource within the group, the delete operation fails.
+- The [What-if](./deploy-what-if.md) support isn't yet available.
 - A management group-scoped stack is restricted from deploying to another management group. It can only deploy to the management group of the stack itself or to a child subscription.
-- The PowerShell command help lists a `DeleteResourcesAndResourcesGroups` value for the `ActionOnUnmanage` switch. When this value is used, the command detaches the managed resources and the resource groups. This value will be removed in the next update. Do not use this value.
+- The PowerShell command help lists a `DeleteResourcesAndResourcesGroups` value for the `ActionOnUnmanage` switch. When this value is used, the command detaches the managed resources and the resource groups. This value will be removed in the next update. Don't use this value.
 
 ## Built-in roles
 
@@ -50,8 +50,8 @@ Deployment stacks provide the following benefits:
 
 There are two built-in roles for deployment stack:
 
-- **Azure Deployment Stack Contributor**: Allows users to manage deployment stacks, but cannot create or delete deny assignments within the deployment stacks.
-- **Azure Deployment Stack Owner**: Allows users to manage deployment stacks, including those with deny assignments.
+- **Azure Deployment Stack Contributor**: Allows users to manage deployment stacks, but can't create or delete deny-assignments within the deployment stacks.
+- **Azure Deployment Stack Owner**: Allows users to manage deployment stacks, including those with deny-assignments.
 
 ## Create deployment stacks
 
@@ -61,7 +61,7 @@ A deployment stack resource can be created at resource group, subscription, or m
 - A stack at subscription scope can deploy the template passed-in to a resource group scope (if specified) or the same subscription scope where the deployment stack exists.
 - A stack at management group scope can deploy the template passed-in to the subscription scope specified.
 
-It's important to note that where a deployment stack exists, so is the deny assignment created with the deny settings capability. For example, by creating a deployment stack at subscription scope that deploys the template to resource group scope and with deny settings mode `DenyDelete`, you can easily provision managed resources to the specified resource group and block delete attempts to those resources. By using this approach, you also enhance the security of the deployment stack by separating it at the subscription level, as opposed to the resource group level. This separation ensures that the developer teams working with the provisioned resources only have visibility and write access to the resource groups, while the deployment stack remains isolated at a higher level. This minimizes the number of users that can edit a deployment stack and make changes to its deny assignment. For more information, see [Protect managed resource against deletion](#protect-managed-resources-against-deletion).
+It's important to note that where a deployment stack exists, so is the deny-assignment created with the deny settings capability. For example, by creating a deployment stack at subscription scope that deploys the template to resource group scope and with deny settings mode `DenyDelete`, you can easily provision managed resources to the specified resource group and block delete attempts to those resources. By using this approach, you also enhance the security of the deployment stack by separating it at the subscription level, as opposed to the resource group level. This separation ensures that the developer teams working with the provisioned resources only have visibility and write access to the resource groups, while the deployment stack remains isolated at a higher level. This minimizes the number of users that can edit a deployment stack and make changes to its deny-assignment. For more information, see [Protect managed resource against deletion](#protect-managed-resources-against-deletion).
 
 The create-stack commands can also be used to [update deployment stacks](#update-deployment-stacks).
 
@@ -294,7 +294,7 @@ Set-AzSubscriptionDeploymentStack `
   -DenySettingsMode "none"
 ```
 
-The `DeploymentResourceGroupName` parameter specifies the resource group used to store the deployment stack resources. If you don't specify a resource group name, the deployment stack service will create a new resource group for you.
+The `DeploymentResourceGroupName` parameter specifies the resource group used to store the deployment stack resources. If you don't specify a resource group name, the deployment stack service creates a new resource group for you.
 
 # [CLI](#tab/azure-cli)
 
@@ -348,7 +348,7 @@ Currently not implemented.
 
 ### Use the New command
 
-You get a warning similar to the following:
+You get a warning similar to the following one:
 
 ```warning
 The deployment stack 'myStack' you're trying to create already exists in the current subscription/management group/resource group. Do you want to overwrite it? Detaching: resources, resourceGroups (Y/N)
@@ -408,6 +408,54 @@ Currently not implemented.
 > [!WARNING]
 > When deleting resource groups with the action-on-unmanage switch set to `DeleteAll`, the managed resource groups and all the resources contained within them will also be deleted.
 
+### Handle the stack-out-of-sync error
+
+When updating or deleting a deployment stack, you might encounter the following stack-out-of-sync error, indicating the stack resource list isn't correctly synchronized. 
+
+```error
+The deployment stack '{0}' may not have an accurate list of managed resources. To ensure no resources are accidentally deleted, please check that the managed resource list does not have any additional values. If there is any uncertainty, we recommend redeploying the stack with the same template and parameters as the current iteration. To bypass this warning, please specify the 'BypassStackOutOfSyncError' flag.
+```
+
+You can obtain a list of the resources from the Azure portal or redeploy the currently deployed Bicep file with the same parameters. The output shows the managed resources
+
+# [PowerShell](#tab/azure-powershell)
+
+```output
+...
+Resources: /subscriptions/9e8db52a-71bc-4871-9007-1117bf304622/resourceGroups/demoRg/providers/Microsoft.Network/virtualNetworks/vnetthmimleef5fwk
+           /subscriptions/9e8db52a-71bc-4871-9007-1117bf304622/resourceGroups/demoRg/providers/Microsoft.Storage/storageAccounts/storethmimleef5fwk
+```
+
+# [CLI](#tab/azure-cli)
+
+```output
+"resources": [
+  {
+    "denyStatus": "none",
+    "id": "/subscriptions/9e8db52a-71bc-4871-9007-1117bf304622/resourceGroups/demoRg/providers/Microsoft.Network/virtualNetworks/vnetthmimleef5fwk",
+    "resourceGroup": "demoRg",
+    "status": "managed"
+  },
+  {
+    "denyStatus": "none",
+    "id": "/subscriptions/9e8db52a-71bc-4871-9007-1117bf304622/resourceGroups/demoRg/providers/Microsoft.Storage/storageAccounts/storethmimleef5fwk",
+    "resourceGroup": "demoRg",
+    "status": "managed"
+  }
+]
+```
+
+# [Portal](#tab/azure-portal)
+
+1. Open the Azure portal.
+1. Open the Resource group that contains the stack.
+1. From the left menu, expand **Settings**, and then select **Deployment stacks**.
+1. Select the stack name to open the stack.
+
+---
+
+After you have reviewed and verified the list of resources in the stack, you can rerun the command with the `BypassStackOutOfSyncError` switch in Azure PowerShell (or `bypass-stack-out-of-sync-error` in Azure CLI). This switch should only be used after thoroughly review the list of resources in the stack before rerunning the command. This switch should never be used by default.
+
 ## Delete deployment stacks
 
 # [PowerShell](#tab/azure-powershell)
@@ -434,7 +482,7 @@ Select one of the delete flags when you delete a deployment stack.
 
 ---
 
-Even if you specify the delete all switch, if there are unmanaged resources within the resource group where the deployment stack is located, both the unmanaged resource and the resource group itself won't  be deleted.
+Even if you specify the delete-all switch, unmanaged resources within the resource group where the deployment stack is located prevents both the unmanaged resources and the resource group itself from being deleted.
 
 To delete deployment stack resources at the resource group scope:
 
@@ -629,7 +677,7 @@ When creating a deployment stack, it's possible to assign a specific type of per
 
 # [PowerShell](#tab/azure-powershell)
 
-The Azure PowerShell includes these parameters to customize the deny assignment:
+The Azure PowerShell includes these parameters to customize the deny-assignment:
 
 - `DenySettingsMode`: Defines the operations that are prohibited on the managed resources to safeguard against unauthorized security principals attempting to delete or update them. This restriction applies to everyone unless explicitly granted access. The values include: `None`, `DenyDelete`, and `DenyWriteAndDelete`.
 - `DenySettingsApplyToChildScopes`: Deny settings are applied to nested resources under managed resources.
@@ -638,7 +686,7 @@ The Azure PowerShell includes these parameters to customize the deny assignment:
 
 # [CLI](#tab/azure-cli)
 
-The Azure CLI includes these parameters to customize the deny assignment:
+The Azure CLI includes these parameters to customize the deny-assignment:
 
 - `deny-settings-mode`: Defines the operations that are prohibited on the managed resources to safeguard against unauthorized security principals attempting to delete or update them. This restriction applies to everyone unless explicitly granted access. The values include: `none`, `denyDelete`, and `denyWriteAndDelete`.
 - `deny-settings-apply-to-child-scopes`: Deny settings are applied to nested resources under managed resources.