Merge pull request #113115 from tfitzmac/0428whatif

add azure cli for what-if

Author: denrea

articles/azure-resource-manager/templates/template-deploy-what-if.md

@@ -3,23 +3,21 @@ title: Template deployment what-if (Preview)
 description: Determine what changes will happen to your resources before deploying an Azure Resource Manager template.
 author: mumian
 ms.topic: conceptual
-ms.date: 04/27/2020
+ms.date: 04/28/2020
 ms.author: jgao
 ---
 # ARM template deployment what-if operation (Preview)
 
-Before deploying an Azure Resource Manager (ARM) template, you might want to preview the changes that will happen. Azure Resource Manager provides the what-if operation to let you see how resources will change if you deploy the template. The what-if operation doesn't make any changes to existing resources. Instead, it predicts the changes if the specified template is deployed.
+Before deploying an Azure Resource Manager (ARM) template, you can preview the changes that will happen. Azure Resource Manager provides the what-if operation to let you see how resources will change if you deploy the template. The what-if operation doesn't make any changes to existing resources. Instead, it predicts the changes if the specified template is deployed.
 
 > [!NOTE]
 > The what-if operation is currently in preview. As a preview release, the results may sometimes show that a resource will change when actually no change will happen. We're working to reduce these issues, but we need your help. Please report these issues at [https://aka.ms/whatifissues](https://aka.ms/whatifissues).
 
-You can use the what-if operation with the PowerShell commands or REST API operations.
+You can use the what-if operation with Azure PowerShell, Azure CLI, or REST API operations.
 
 ## Install PowerShell module
 
-To use what-if in PowerShell, you must have PowerShell Core (6.x or 7.x). If you have PowerShell 5.x or earlier, [update your version of PowerShell](/powershell/scripting/install/installing-powershell).
-
-After making sure you have the correct version of PowerShell, install a preview version of the Az.Resources module from the PowerShell gallery.
+To use what-if in PowerShell, you must install a preview version of the Az.Resources module from the PowerShell gallery. But, before installing the module, make sure you have PowerShell Core (6.x or 7.x). If you have PowerShell 5.x or earlier, [update your version of PowerShell](/powershell/scripting/install/installing-powershell). You can't install the preview module on PowerShell 5.x or earlier.
 
 ### Install preview version
 
@@ -54,9 +52,13 @@ If you previously installed an alpha version of the what-if module, uninstall th
 
 You're ready to use what-if.
 
+## Install Azure CLI module
+
+To use what-if in Azure CLI, you must have Azure CLI 2.5.0 or later. If needed, [install the latest version of Azure CLI](/cli/azure/install-azure-cli).
+
 ## See results
 
-In PowerShell, the output includes color-coded results that help you see the different types of changes.
+When you use what-if in PowerShell or Azure CLI, the output includes color-coded results that help you see the different types of changes.
 
 ![Resource Manager template deployment what-if operation fullresourcepayload and change types](./media/template-deploy-what-if/resource-manager-deployment-whatif-change-types.png)
 
@@ -91,11 +93,9 @@ Resource changes: 1 to modify.
 
 ## What-if commands
 
-You can use either Azure PowerShell or Azure REST API for the what-if operation.
-
 ### Azure PowerShell
 
-To see a preview of the changes before deploying a template, add the `-Whatif` switch parameter to the deployment command.
+To preview changes before deploying a template, add the `-Whatif` switch parameter to the deployment command.
 
 * `New-AzResourceGroupDeployment -Whatif` for resource group deployments
 * `New-AzSubscriptionDeployment -Whatif` and `New-AzDeployment -Whatif` for subscription level deployments
@@ -110,6 +110,23 @@ The preceding commands return a text summary that you can manually inspect. To g
 * `$results = Get-AzResourceGroupDeploymentWhatIfResult` for resource group deployments
 * `$results = Get-AzSubscriptionDeploymentWhatIfResult` or `$results = Get-AzDeploymentWhatIfResult` for subscription level deployments
 
+### Azure CLI
+
+To preview changes before deploying a template, use `what-if` with the deployment command.
+
+* `az deployment group what-if` for resource group deployments
+* `az deployment sub what-if` for subscription level deployments
+
+Or, you can use the `--confirm-with-what-if` parameter to preview the changes and get prompted to continue with the deployment.
+
+* `az deployment group create --confirm-with-what-if` for resource group deployments
+* `az deployment sub create --confirm-with-what-if` for subscription level deployments
+
+The preceding commands return a text summary that you can manually inspect. To get a JSON object that you can programmatically inspect for changes, use:
+
+* `az deployment group what-if --no-pretty-print` for resource group deployments
+* `az deployment sub what-if --no-pretty-print` for subscription level deployments
+
 ### Azure REST API
 
 For REST API, use:
@@ -135,10 +152,17 @@ The what-if operation lists six different types of changes:
 
 ## Result format
 
-You can control the level of detail that is returned about the predicted changes. In the deployment commands (`New-Az*Deployment`), use the **-WhatIfResultFormat** parameter. In the programmatic object commands (`Get-Az*DeploymentWhatIf`), use the **ResultFormat** parameter.
+You control the level of detail that is returned about the predicted changes. You have two options:
+
+* **FullResourcePayloads** - returns a list of resources that will change and details about the properties that will change
+* **ResourceIdOnly** - returns a list of resources that will change
+
+The default value is **FullResourcePayloads**.
 
-Set the format parameter to **FullResourcePayloads** to get a list of resources that will change and details about the properties that will change. Set the format parameter to **ResourceIdOnly** to get a list of resources that will change. The default value is **FullResourcePayloads**.  
+For PowerShell deployment commands, use the `-WhatIfResultFormat` parameter. In the programmatic object commands, use the `ResultFormat` parameter.
 
+For Azure CLI, use the `--result-format` parameter.
+ 
 The following results show the two different output formats:
 
 - Full resource payloads
@@ -191,6 +215,8 @@ The following results show the two different output formats:
 
 To see how what-if works, let's runs some tests. First, deploy a [template that creates a virtual network](https://github.com/Azure/azure-docs-json-samples/blob/master/azure-resource-manager/what-if/what-if-before.json). You'll use this virtual network to test how changes are reported by what-if.
 
+# [PowerShell](#tab/azure-powershell)
+
 ```azurepowershell
 New-AzResourceGroup `
   -Name ExampleGroup `
@@ -200,9 +226,24 @@ New-AzResourceGroupDeployment `
   -TemplateUri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/azure-resource-manager/what-if/what-if-before.json"
 ```
 
+# [Azure CLI](#tab/azure-cli)
+
+```azurecli
+az group create \
+  --name ExampleGroup \
+  --location "Central US"
+az deployment group create \
+  --resource-group ExampleGroup \
+  --template-uri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/azure-resource-manager/what-if/what-if-before.json"
+```
+
+---
+
 ### Test modification
 
-After the deployment completes, you're ready to test the what-if operation. This time deploy a [template that changes the virtual network](https://github.com/Azure/azure-docs-json-samples/blob/master/azure-resource-manager/what-if/what-if-after.json). It's missing one the original tags, a subnet has been removed, and the address prefix has changed.
+After the deployment completes, you're ready to test the what-if operation. This time you deploy a [template that changes the virtual network](https://github.com/Azure/azure-docs-json-samples/blob/master/azure-resource-manager/what-if/what-if-after.json). It's missing one the original tags, a subnet has been removed, and the address prefix has changed.
+
+# [PowerShell](#tab/azure-powershell)
 
 ```azurepowershell
 New-AzResourceGroupDeployment `
@@ -211,6 +252,16 @@ New-AzResourceGroupDeployment `
   -TemplateUri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/azure-resource-manager/what-if/what-if-after.json"
 ```
 
+# [Azure CLI](#tab/azure-cli)
+
+```azurecli
+az deployment group what-if \
+  --resource-group ExampleGroup \
+  --template-uri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/azure-resource-manager/what-if/what-if-after.json"
+```
+
+---
+
 The what-if output appears similar to:
 
 ![Resource Manager template deployment what-if operation output](./media/template-deploy-what-if/resource-manager-deployment-whatif-change-types.png)
@@ -254,6 +305,8 @@ Some of the properties that are listed as deleted won't actually change. Propert
 
 Now, let's programmatically evaluate the what-if results by setting the command to a variable.
 
+# [PowerShell](#tab/azure-powershell)
+
 ```azurepowershell
 $results = Get-AzResourceGroupDeploymentWhatIfResult `
   -ResourceGroupName ExampleGroup `
@@ -269,20 +322,42 @@ foreach ($change in $results.Changes)
 }
 ```
 
+# [Azure CLI](#tab/azure-cli)
+
+```azurecli
+results=$(az deployment group what-if --resource-group ExampleGroup --template-uri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/azure-resource-manager/what-if/what-if-after.json" --no-pretty-print)
+```
+
+---
+
 ## Confirm deletion
 
 The what-if operation supports using [deployment mode](deployment-modes.md). When set to complete mode, resources not in the template are deleted. The following example deploys a [template that has no resources defined](https://github.com/Azure/azure-docs-json-samples/blob/master/empty-template/azuredeploy.json) in complete mode.
 
 To preview changes before deploying a template, use the `-Confirm` switch parameter with the deployment command. If the changes are as you expected, confirm that you want the deployment to complete.
 
+# [PowerShell](#tab/azure-powershell)
+
 ```azurepowershell
 New-AzResourceGroupDeployment `
-  -Confirm `
   -ResourceGroupName ExampleGroup `
-  -TemplateUri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/empty-template/azuredeploy.json" `
-  -Mode Complete
+  -Mode Complete `
+  -Confirm `
+  -TemplateUri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/empty-template/azuredeploy.json"
 ```
 
+# [Azure CLI](#tab/azure-cli)
+
+```azurecli
+az deployment group create \
+  --resource-group ExampleGroup \
+  --mode Complete \
+  --confirm-with-what-if \
+  --template-uri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/empty-template/azuredeploy.json"
+```
+
+---
+
 Because no resources are defined in the template and the deployment mode is set to complete, the virtual network will be deleted.
 
 ![Resource Manager template deployment what-if operation output deployment mode complete](./media/template-deploy-what-if/resource-manager-deployment-whatif-output-mode-complete.png)
@@ -320,4 +395,5 @@ You see the expected changes and can confirm that you want the deployment to run
 
 - If you notice incorrect results from the preview release of what-if, please report the issues at [https://aka.ms/whatifissues](https://aka.ms/whatifissues).
 - To deploy templates with Azure PowerShell, see [Deploy resources with ARM templates and Azure PowerShell](deploy-powershell.md).
+- To deploy templates with Azure CLI, see [Deploy resources with ARM templates and Azure CLI](deploy-cli.md).
 - To deploy templates with REST, see [Deploy resources with ARM templates and Resource Manager REST API](deploy-rest.md).