If you are familiar with Terraform, you know it has a plan option to see what changes Terraform will make. Did you know Azure PowerShell has the same option? You can use the PowerShell -WhatIf parameter during your ARM template deployments to preview the changes!
This tutorial has a brief review of deploying ARM templates using PowerShell, then demonstrates adding the -WhatIf PowerShell parameter and interpreting the results.
Reviewing ARM Template Deployments Using PowerShell
ARM templates are JSON-formatted files that describe what your Azure environment should look like. You then deploy the code using commands from the Az PowerShell module (or Azure CLI if you prefer). The Azure Resource Manager service then takes the code and deploys the infrastructure for you. You deploy ARM templates at the management group, tenant, subscription, or resource group level.
To learn more about ARM templates, check out Exploring ARM Templates: Azure Resource Manager Tutorial!
Here is an example of an ARM template that deploys a virtual network (vnet1) and one subnet (snet1). For demo simplicity, many values are hard-coded and not using parameters or variables. If you are following along, save this code to a file named azuredeploy-vnet.json on your local system.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"resources": [
{
"name": "vnet1",
"type": "Microsoft.Network/virtualNetworks",
"apiVersion": "2020-11-01",
"location": "[resourceGroup().location]",
"properties": {
"addressSpace": {
"addressPrefixes": [
"10.10.0.0/16"
]
},
"subnets": [
{
"name": "snet1",
"properties": {
"addressPrefix": "10.10.5.0/24"
}
}
]
}
}
]
}
To deploy this ARM template, use the New-AzResourceGroupDeployment command and specify the name of an existing resource group (rg-armdemo) and the name of the ARM template file (azuredeploy-vnet.json).
New-AzResourceGroupDeployment `
-ResourceGroupName 'rg-armdemo' `
-TemplateFile azuredeploy-vnet.json
Use -WhatIf to Preview ARM Deployment
Before deploying the ARM template above, you can preview the deployment’s impact by adding the -WhatIf to the New-AzResourceGroupDeployment PowerShell command. If you are a regular PowerShell user, the -WhatIf parameter shows the impact of the command.
In the case of New-AzResourceGroupDeployment, PowerShell outputs what impact the ARM template has on Azure infrastructure. Here is the updated command with the -WhatIf parameter.
New-AzResourceGroupDeployment `
-ResourceGroupName 'rg-armdemo' `
-TemplateFile azuredeploy-vnet.json `
-WhatIf
And here is the output! Note that PowerShell indicates the resource and property changes using symbols and font colors. A plus sign (+) and the green text show the ARM template deploys a new resource that doesn’t already exist. In this case, the ARM template deploys a new virtual network and subnet.
At the end of the output, Azure displays a summary of the kinds of changes being made. In this case, Azure will create one resource.
At this point, you should feel confident in the ARM template’s actions and remove the -WhatIf to perform the actual deployment.
Preview Modifications
If you add or change a property of the virtual network in the ARM template, you can rerun the same -WhatIf command to view the modifications. Let’s say you need to add resource tags to the virtual network, like the environment and cost center. Here’s a snippet of the updated ARM template with the resource tags defined.
# Start snippet
"name": "vnet1",
"type": "Microsoft.Network/virtualNetworks",
"apiVersion": "2020-11-01",
"location": "[resourceGroup().location]",
"tags": {
"env": "prod",
"cost_center": "IT"
},
# End snippet
Running the New-AzResourceGroupDeployment command with -WhatIf now indicates that the ARM template modifies the virtual network by using a tilde (~) in the color purple. Also, note that the resource tags are green as the tags are new to the virtual network.
Preview Deletions
Finally, if you remove a property or resource from an ARM template, -WhatIf shows this to you too! Remove the subnet definition from the ARM template and rerun your command. Azure indicates that the ARM template deletes the subnet using an orange minus sign (-).
Formatting WhatIf Output
In addition to the -WhatIf parameter are two additional parameters:
- WhatIfResultFormat: takes accepts FullResourcePayloads (default) and ResourceIdOnly as values
- WhatIfExcludeChangeType: accepts Create, Deploy, NoChange, Ignore, Modify, and Deletes as values
WhatIfResultFormat
For example, setting the -WhatIfResultFormat to ResourceIdOnly changes the output from the default to show only the resource ID of the modified resource but not what changes Azure will make.
In this example, the output shows vnet1 will be modified but does indicate the new subnet that you added to the ARM template. Also, note this displays a new change type of Deploy with an exclamation point (!) in blue font.
New-AzResourceGroupDeployment `
-ResourceGroupName 'rg-armdemo' `
-TemplateFile azuredeploy-vnet.json `
-WhatIf `
-WhatIfResultFormat ResourceIdOnly
WhatIfExcludeChangeType
The -WhatIfExcludeChangeType is a list of change types to ignore in the output. You have already seen several change types of Create, Modify, Delete, and Deploy. If you want to see only the delete actions, include all other change types. Excluding change types allow you to focus only on the changes you care about.
One thing to watch out for is how a resource can have multiple change types associated with it. Note the modification and deletion examples from earlier. The results show the virtual network being modified while virtual network properties are created or deleted. If you exclude the Modify change type, the output does not show the created or deleted properties.
For example, suppose you rerun the deployment command with the ARM template configuration where the subnet is deleted and exclude the Modify change type. In that case, the output shows Azure will make no changes.
New-AzResourceGroupDeployment `
-ResourceGroupName 'rg-armdemo' `
-TemplateFile azuredeploy-vnet.json `
-WhatIf
-WhatIfExcludeChangeType Modify
Closing
The -WhatIf output is an excellent tool for previewing changes made by the ARM template configuration. If you notice an inaccuracy in the output, you can notify the development team by opening a GitHub issue using this URL:
Enjoyed this article? Leave a comment below and check out more of my Azure and PowerShell content!
