Merge branch 'main' of https://github.com/MicrosoftDocs/azure-docs-pr into us416874-freshness-update-ts

Author: asudbring

articles/azure-resource-manager/bicep/migrate.md

@@ -2,7 +2,7 @@
 title: Migrate Azure resources and JSON ARM templates to use Bicep
 description: Learn the recommended workflow when migrating Azure resources and JSON ARM templates to use Bicep.
 ms.topic: conceptual
-ms.date: 01/10/2025
+ms.date: 04/02/2025
 ms.custom: devx-track-bicep
 author: joshuawaddell
 ms.author: jowaddel
@@ -28,7 +28,7 @@ In the _convert_ phase of migrating your resources to Bicep, the goal is to capt
 
 The convert phase consists of two steps, which you complete in sequence:
 
-1. **Capture a representation of your Azure resources.** If you have an existing JSON template that you're converting to Bicep, the first step is easy - you already have your source template. If you're converting Azure resources that were deployed by using the portal or another tool, you need to capture the resource definitions. You can capture a JSON representation of your resources using the Azure portal, Azure CLI, or Azure PowerShell cmdlets to *export* single resources, multiple resources, and entire resource groups. You can use the `Insert Resource` command within Visual Studio Code to import a Bicep representation of your Azure resource.
+1. **Capture a representation of your Azure resources.** If you have an existing JSON template that you're converting to Bicep, the first step is easy - you already have your source template. If you're converting Azure resources that were deployed by using the portal or another tool, you need to capture the resource definitions. You can capture a JSON representation of your resources using the Azure portal, Azure CLI, or Azure PowerShell cmdlets to _export_ single resources, multiple resources, and entire resource groups. You can use the `Insert Resource` command within Visual Studio Code to import a Bicep representation of your Azure resource.
 
 1. **If required, convert the JSON representation to Bicep using the _decompile_ command.** [The Bicep tooling includes the `decompile` command to convert templates.](decompile.md) You can invoke the `decompile` command from [Visual Studio Code with the Bicep extension](./visual-studio-code.md#decompile-into-bicep-command), the [Azure CLI](./bicep-cli.md#decompile), or from the [Bicep CLI](./bicep-cli.md#decompile). The decompilation process is a best-effort process and doesn't guarantee a full mapping from JSON to Bicep. You may need to revise the generated Bicep file to meet your template best practices before using the file to deploy resources.
 
@@ -80,7 +80,7 @@ In the _test_ phase of migrating your resources to Bicep, the goal is to verify
 
 The test phase consists of two steps, which you complete in sequence:
 
-1. **Run the ARM template deployment what-if operation.** To help you verify your converted templates before deployment, you can use the [Azure Resource Manager template deployment what-if operation](../templates/deploy-what-if.md). It compares the current state of your environment with the desired state that is defined in the template. The tool outputs the list of changes that will occur *without* applying the changes to your environment. You can use what-if with both incremental and complete mode deployments. Even if you plan to deploy your template using incremental mode, it's a good idea to run your what-if operation in complete mode.
+1. **Run the ARM template deployment what-if operation.** To help you verify your converted templates before deployment, you can use the [Azure Resource Manager template deployment what-if operation](../templates/deploy-what-if.md). It compares the current state of your environment with the desired state that is defined in the template. The tool outputs the list of changes that will occur _without_ applying the changes to your environment. You can use what-if with both [incremental mode](../templates/deployment-modes.md#incremental-mode) and [complete mode](../templates/deployment-modes.md#complete-mode) deployments. Even if you plan to deploy your template using incremental mode, it's a good idea to run your what-if operation in complete mode.
 
 1. **Perform a test deployment.** Before introducing your converted Bicep template to production, consider running multiple test deployments. If you have multiple environments (for example, development, test, and production), you may want to try deploying your template to one of your non-production environments first. After the deployment, compare the original resources with the new resource deployments for consistency.
 
@@ -96,7 +96,7 @@ The deploy phase consists of four steps, which you complete in sequence:
 
 1. **Deploy manually.** If you're going to use the converted template in a pipeline, such as [Azure DevOps](add-template-to-azure-pipelines.md) or [GitHub Actions](deploy-github-actions.md), consider running the deployment from your local machine first. It's preferable to test the template's functionality before incorporating it into your production pipeline. That way, you can respond quickly if there's a problem.
 
-1. **Run smoke tests.** After your deployment is complete, you should run a series of *smoke tests* to ensure that your application or workload is working properly. For example, test to see if your web app is accessible through normal access channels, such as the public Internet or across a corporate VPN. For databases, attempt to make a database connection and execute a series of queries. With virtual machines, sign in to the virtual machine and make sure that all services are up and running.
+1. **Run smoke tests.** After your deployment is complete, you should run a series of _smoke tests_ to ensure that your application or workload is working properly. For example, test to see if your web app is accessible through normal access channels, such as the public Internet or across a corporate VPN. For databases, attempt to make a database connection and execute a series of queries. With virtual machines, sign in to the virtual machine and make sure that all services are up and running.
 
 ## Next steps
 

articles/azure-resource-manager/templates/deployment-modes.md

@@ -3,17 +3,37 @@ title: Deployment modes
 description: Describes how to specify whether to use a complete or incremental deployment mode with Azure Resource Manager.
 ms.topic: conceptual
 ms.custom: devx-track-arm-template
-ms.date: 03/20/2024
+ms.date: 04/02/2025
 ---
 
 # Azure Resource Manager deployment modes
 
 When deploying your resources, you specify that the deployment is either an incremental update or a complete update. The difference between these two modes is how Resource Manager handles existing resources in the resource group that aren't in the template.
 
+> [!IMPORTANT]
+> Use [deployment stacks](../bicep/deployment-stacks.md) to perform resource deletions when using ARM templates or Bicep files, as the [complete mode](#complete-mode) will be gradually deprecated.
+
 For both modes, Resource Manager tries to create all resources specified in the template. If the resource already exists in the resource group and its settings are unchanged, no operation is taken for that resource. If you change the property values for a resource, the resource is updated with those new values. If you try to update the location or type of an existing resource, the deployment fails with an error. Instead, deploy a new resource with the location or type that you need.
 
 The default mode is incremental.
 
+## Incremental mode
+
+In incremental mode, Resource Manager **leaves unchanged** resources that exist in the resource group but aren't specified in the template. Resources in the template **are added** to the resource group.
+
+> [!IMPORTANT]
+>
+> Incremental mode is the recommended deployment dode. If there is a need to delete resources as part of a Bicep file or ARM JSON template, use [deployment stacks](../bicep/deployment-stacks.md).
+>
+> When redeploying an existing resource in incremental mode, all properties are reapplied. The **properties aren't incrementally added**. A common misunderstanding is to think properties that aren't specified in the template are left unchanged. If you don't specify certain properties, Resource Manager interprets the deployment as overwriting those values. Properties that aren't included in the template are reset to the default values. Specify all non-default values for the resource, not just the ones you're updating. The resource definition in the template always contains the final state of the resource. It can't represent a partial update to an existing resource.
+
+> [!WARNING]
+> In rare cases, you can specify properties either on a resource or on one of its child resources. Two common examples are **subnets on virtual networks** and **site configuration values for web apps**. In these cases, you must handle incremental updates carefully.
+>
+> For subnets, specify the values through the `subnets` property on the [Microsoft.Network/virtualNetworks](/azure/templates/microsoft.network/virtualnetworks) resource. Don't define the values through the child resource [Microsoft.Network/virtualNetworks/subnets](/azure/templates/microsoft.network/virtualnetworks/subnets). As long as the subnets are defined on the virtual network, you can redeploy the virtual network and not lose the subnets.
+>
+> For site configuration values, the values are implemented in the child resource type `Microsoft.Web/sites/config`. If you redeploy the web app and specify an empty object for the site configuration values, the child resource isn't updated. However, if you provide new site configuration values, the child resource type is updated.
+
 ## Complete mode
 
 In complete mode, Resource Manager **deletes** resources that exist in the resource group but aren't specified in the template.
@@ -43,20 +63,6 @@ If the resource group is [locked](../management/lock-resources.md), complete mod
 > Currently, the portal doesn't support complete mode.
 >
 
-## Incremental mode
-
-In incremental mode, Resource Manager **leaves unchanged** resources that exist in the resource group but aren't specified in the template. Resources in the template **are added** to the resource group.
-
-> [!IMPORTANT]
-> When redeploying an existing resource in incremental mode, all properties are reapplied. The **properties aren't incrementally added**. A common misunderstanding is to think properties that aren't specified in the template are left unchanged. If you don't specify certain properties, Resource Manager interprets the deployment as overwriting those values. Properties that aren't included in the template are reset to the default values. Specify all non-default values for the resource, not just the ones you're updating. The resource definition in the template always contains the final state of the resource. It can't represent a partial update to an existing resource.
-
-> [!WARNING]
-> In rare cases, you can specify properties either on a resource or on one of its child resources. Two common examples are **subnets on virtual networks** and **site configuration values for web apps**. In these cases, you must handle incremental updates carefully.
->
-> For subnets, specify the values through the `subnets` property on the [Microsoft.Network/virtualNetworks](/azure/templates/microsoft.network/virtualnetworks) resource. Don't define the values through the child resource [Microsoft.Network/virtualNetworks/subnets](/azure/templates/microsoft.network/virtualnetworks/subnets). As long as the subnets are defined on the virtual network, you can redeploy the virtual network and not lose the subnets.
->
-> For site configuration values, the values are implemented in the child resource type `Microsoft.Web/sites/config`. If you redeploy the web app and specify an empty object for the site configuration values, the child resource isn't updated. However, if you provide new site configuration values, the child resource type is updated.
-
 ## Example result
 
 To illustrate the difference between incremental and complete modes, consider the following scenario.