|
| 1 | +--- |
| 2 | +title: Template deployment what-if (Preview) |
| 3 | +description: Determine what changes will happen to your resources before deploying an Azure Resource Manager template. |
| 4 | +author: mumian |
| 5 | +ms.service: azure-resource-manager |
| 6 | +ms.topic: conceptual |
| 7 | +ms.date: 11/12/2019 |
| 8 | +ms.author: jgao |
| 9 | + |
| 10 | +--- |
| 11 | +# Resource Manager template deployment what-if operation (Preview) |
| 12 | + |
| 13 | +Before deploying a 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. |
| 14 | + |
| 15 | +> [!NOTE] |
| 16 | +> The what-if operation is currently in preview. To use it, you must [sign up for the preview](https://aka.ms/armtemplatepreviews). 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/armwhatifissues](https://aka.ms/armwhatifissues). |
| 17 | +
|
| 18 | +You can use the what-if operation with the `New-AzDeploymentWhatIf` PowerShell command or the [Deployments - What If](/rest/api/resources/deployments/whatif) REST operation. |
| 19 | + |
| 20 | +In PowerShell, the output looks like: |
| 21 | + |
| 22 | + |
| 23 | + |
| 24 | +## Change types |
| 25 | + |
| 26 | +The what-if operation lists six different types of changes: |
| 27 | + |
| 28 | +- **Create**: The resource doesn't currently exist but is defined in the template. The resource will be created. |
| 29 | + |
| 30 | +- **Delete**: This change type only applies when using [complete mode](deployment-modes.md) for deployment. The resource exists, but isn't defined in the template. With complete mode, the resource will be deleted. Only resources that [support complete mode deletion](complete-mode-deletion.md) are included in this change type. |
| 31 | + |
| 32 | +- **Ignore**: The resource exists, but isn't defined in the template. The resource won't be deployed or modified. |
| 33 | + |
| 34 | +- **NoChange**: The resource exists, and is defined in the template. The resource will be redeployed, but the properties of the resource won't change. This change type is returned when [ResultFormat](#result-format) is set to `FullResourcePayloads`, which is the default value. |
| 35 | + |
| 36 | +- **Modify**: The resource exists, and is defined in the template. The resource will be redeployed, and the properties of the resource will change. This change type is returned when [ResultFormat](#result-format) is set to `FullResourcePayloads`, which is the default value. |
| 37 | + |
| 38 | +- **Deploy**: The resource exists, and is defined in the template. The resource will be redeployed. The properties of the resource may or may not change. The operation returns this change type when it doesn't have enough information to determine if any properties will change. You only see this condition when [ResultFormat](#result-format) is set to `ResourceIdOnly`. |
| 39 | + |
| 40 | +## Deployment scope |
| 41 | + |
| 42 | +You can use the what-if operation for deployments at either the subscription or resource group level. You set the deployment scope with the `-ScopeType` parameter. The accepted values are `Subscription` and `ResourceGroup`. This article demonstrates resource group deployments. |
| 43 | + |
| 44 | +To learn about subscription level deployments, see [Create resource groups and resources at the subscription level](deploy-to-subscription.md#). |
| 45 | + |
| 46 | +## Result format |
| 47 | + |
| 48 | +You can control the level of detail that is returned about the predicted changes. Set the `ResultFormat` parameter to `FullResourcePayloads` to get a list of resources what will change and details about the properties that will change. Set the `ResultFormat` parameter to `ResourceIdOnly` to get a list of resources that will change. The default value is `FullResourcePayloads`. |
| 49 | + |
| 50 | +The following screenshots show the two different output formats: |
| 51 | + |
| 52 | +- Full resource payloads |
| 53 | + |
| 54 | +  |
| 55 | + |
| 56 | +- Resource ID only |
| 57 | + |
| 58 | +  |
| 59 | + |
| 60 | +## Run what-if operation |
| 61 | + |
| 62 | +### Set up environment |
| 63 | + |
| 64 | +To see how what-if works, let's runs some tests. First, deploy a template from [Azure Quickstart templates that creates a storage account](https://github.com/Azure/azure-quickstart-templates/blob/master/101-storage-account-create/azuredeploy.json). The default storage account type is `Standard_LRS`. You'll use this storage account to test how changes are reported by what-if. |
| 65 | + |
| 66 | +```azurepowershell-interactive |
| 67 | +New-AzResourceGroup ` |
| 68 | + -Name ExampleGroup ` |
| 69 | + -Location centralus |
| 70 | +New-AzResourceGroupDeployment ` |
| 71 | + -ResourceGroupName ExampleGroup ` |
| 72 | + -TemplateUri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/101-storage-account-create/azuredeploy.json" |
| 73 | +``` |
| 74 | + |
| 75 | +### Test modification |
| 76 | + |
| 77 | +After the deployment completes, you're ready to test the what-if operation. Run the what-if command but change the storage account type to `Standard_GRS`. |
| 78 | + |
| 79 | +```azurepowershell-interactive |
| 80 | +New-AzDeploymentWhatIf ` |
| 81 | + -ScopeType ResourceGroup ` |
| 82 | + -ResourceGroupName ExampleGroup ` |
| 83 | + -TemplateUri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/101-storage-account-create/azuredeploy.json" ` |
| 84 | + -storageAccountType Standard_GRS |
| 85 | +``` |
| 86 | + |
| 87 | +The what-if output is similar to: |
| 88 | + |
| 89 | + |
| 90 | + |
| 91 | +Notice at the top of the output that colors are defined to indicate the type of changes. |
| 92 | + |
| 93 | +At the bottom of the output, it shows the sku name (storage account type) will be changed from **Standard_LRS** to **Standard_GRS**. |
| 94 | + |
| 95 | +### Test deletion |
| 96 | + |
| 97 | +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. |
| 98 | + |
| 99 | +```azurepowershell-interactive |
| 100 | +New-AzDeploymentWhatIf ` |
| 101 | + -ScopeType ResourceGroup ` |
| 102 | + -ResourceGroupName ExampleGroup ` |
| 103 | + -TemplateUri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/empty-template/azuredeploy.json" ` |
| 104 | + -Mode Complete |
| 105 | +``` |
| 106 | + |
| 107 | +Because no resources are defined in the template and the deployment mode is set to complete, the storage account will be deleted. |
| 108 | + |
| 109 | + |
| 110 | + |
| 111 | +It's important to remember what-if makes no actual changes. The storage account still exists in your resource group. |
| 112 | + |
| 113 | +## Next steps |
| 114 | + |
| 115 | +- If you notice incorrect results from the preview release of what-if, please report the issues at [https://aka.ms/armwhatifissues](https://aka.ms/armwhatifissues). |
| 116 | +- To deploy templates with Azure PowerShell, see [Deploy resources with Resource Manager templates and Azure PowerShell](resource-group-template-deploy.md). |
| 117 | +- To deploy templates with REST, see [Deploy resources with Resource Manager templates and Resource Manager REST API](resource-group-template-deploy-rest.md). |
| 118 | +- To roll back to a successful deployment when you get an error, see [Rollback on error to successful deployment](rollback-on-error.md). |
0 commit comments