ARM Deployment Insights

Before deploying an Azure Resource Manager template (ARM template), you can preview the effects of your deployment. Azure Resource Manager provides the what-if operation that enables you to perform a pre-deployment impact assessment and 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.

The what-if operation compares the current state model to the desired state model and allows you to confirm if the changes made by your template match your expectations without actually applying those changes.

This extension brings the power of what-if operation to Azure DevOps pipelines.

Prerequisites

Before you get started, there are some prerequisites you should know about.

• ARMDeploymentInsights task requires Azure CLI to run the what-if operation, and if you are using a self-hosted agent, you need to make sure Azure CLI is installed on the agent. Microsoft-hosted agents come with Azure CLI preinstalled.

ARMDeploymentInsights@1 (v1) task can only run on Windows. It is still available, but it can now be considered as deprecated and will not receive any updates in the future.

Get Started

To get started, all you need to do is include the ARMDeploymentInsights task in your Azure DevOps pipeline. The task acts as a facade for Azure CLI, translating your input parameters to Azure CLI commands. The task input parameters are similar to the input parameters of the AzureResourceManagerTemplateDeployment task (which you might already be using), making it even easier to set up. See example bellow for reference, or go to Task Parameters to read more.

ARMDeploymentInsights@1 (v1) task is deprecated. It is recommended to use ARMDeploymentInsights@2 (v2) task, as it can do everything previous version (v1) can, and also runs on Linux.

- task: ARMDeploymentInsights@2
  inputs:
    deploymentName: 'My Deployment'
    deploymentScope: 'Resource Group'
    armServiceConnection: '<ARM Service Connection>'
    subscriptionId: '<Subscription>'
    resourceGroupName: 'my-resource-group'
    templateLocation: 'File'
    templateFile: '$(System.DefaultWorkingDirectory)/src/arm/azuredeploy.json'
    templateParametersFile: '$(System.DefaultWorkingDirectory)/src/arm/azuredeploy.params.json'

The task collects data via Azure CLI. You don't really need to know what happens "under the hood", but if you are interested, this is how the previous example would get "translated" to the Azure CLI command:

az deployment group what-if --resource-group 'my-resource-group' --template-file '$(System.DefaultWorkingDirectory)/src/arm/azuredeploy.json' --parameters '$(System.DefaultWorkingDirectory)/src/arm/azuredeploy.params.json' --subscription '<Subscription>' --no-pretty-print --no-prompt --result-format=FullResourcePayloads

Azure CLI what-if operation results are stored as build attachments, effectively acting as "what-if snapshots" for a specific pipeline run and deployment.

Results can be viewed under the ARM Deployment Insights build results tab, which appears only if the ARMDeploymentInsights task is included in the pipeline.

Build Results Tab

Multiple Deployments

Build results tab shows what-if operation results split into multiple additional tabs, where each tab represents a single deployment. Tab name (title) can be set via the Deployment Name (deploymentName) input parameter of the ARMDeploymentInsights task. This means that you can preview the effects of more than one deployment in a single pipeline.

In a multi-stage pipeline, where each stage represents a deployment to a different environment, you can perform a pre-deployment impact assessment and see how each environment will be affected before deploying the template.

Scope/Grouping

Changes are grouped by scope, which indicates where the resource will be deployed. For example, if the template includes resources from different resource groups, changes will be grouped under corresponding resource groups.

Change Types

Change type indicates if and how resources will be affected if you deploy the template.

Icon	Name	Description
	Create	The resource does not exist in the current state but is present in the desired state. The resource will be created when the deployment is executed.
	Delete	The resource exists in the current state and is missing from the desired state. The resource will be deleted when the deployment is executed.
	Deploy	The resource exists in the current state and the desired state and will be redeployed when the deployment is executed. The properties of the resource may or may not change.
	Ignore	The resource exists in the current state and is missing from the desired state. The resource will not be deployed or modified when the deployment is executed.
	Modify	The resource exists in the current state and the desired state and will be redeployed when the deployment is executed. The properties of the resource will change.
	No Change	The resource exists in the current state and the desired state and will be redeployed when the deployment is executed. The properties of the resource will not change.
	Unsupported	The resource is not supported by what-if.

Filter

Changes are automatically filtered to show only Create, Delete, Deploy and Modify change types. You can modify the filter to include other change types as well.

If you are looking for a specific resource, you can filter changes by resource name or type.

Details

Select the change to view its details. Each change can have a before and after state, corresponding to the current and desired state of the resource. The Details view can show either current or desired state, or both, depending on the change type.

For example, changes with the Create change type have only desired state because the resource does not exist yet. Likewise, changes with the Delete change type have only current state because the resource does not exist in the desired state. However, some change types have both current and desired states. The details view adapts to all these scenarios and always shows relevant data, favoring the desired state to the current state.

The details view shows both the current and desired state model, side by side, for changes with the Modify change type, so that you can compare them and confirm if the changes made by your template match your expectations.

In the image above, the Before column shows the current state (before deployment), while the After column shows desired state (after deployment).

If you prefer to look at the code, you can switch to a Diff View (Side-by-Side or Inline) and see actual JSON differences between the current and desired state model.

Task Parameters

YAML name is in parenthesis.

• Deployment Name (deploymentName): Name of the deployment to be displayed in the build results tab. Deployment Name also serves as a deployment identifier and must be unique. Therefore, if your build has multiple ARMDeploymentInsights tasks with the same name, only the last one will be displayed. Likewise, if there are multiple attempts of a single ARMDeploymentInsights task, only the last attempt will be displayed.

  Tip: You can set a target environment (e.g., DEV, TEST, PROD) as a deployment name.

  Deployment Name can not contain illegal filename characters.

• Deployment Scope (deploymentScope): Deployment scope of the deployment. It can be set to Management Group, Subscription or Resource Group. Tenant scope is not supported.

  Management Group scope is not supported in the old (v1) task version.

• ARM Service Connection (armServiceConnection): Azure Resource Manager Service Connection with access to the selected deployment scope. Service Principal (including both Key and Certificate authentication types) and Workload Identity Federation are supported authentication methods. Managed Identity is not supported.

• Subscription (subscription or subscriptionId): Azure Subscription ID

• Resource Group (resourceGroup or resourceGroupName): Resource group to execute deployment what-if operation at. It is required only for the Resource Group deployment scope. What-if operation will fail if resource group does not exist.

• Location (location): Location to store what-if operation metadata. It is required for the Management Group and Subscription deployment scopes.

• Template Location (templateLocation): Template Location indicates where the ARM template is located. File means that the template is located in the code repository (together with other files) and is therefore available for the build agent running the task. URI means that the template is located in a remote location, accessible via URI. URI is commonly used together with linked templates. When referencing a linked template, the value of URI can't be a local file or a file that is only available on your local network. Azure Resource Manager must be able to access the template.

• Template (templateFile): Local path or a pattern pointing to the Azure Resource Manager template.

• Template Parameters (templateParametersFile): Local path or a pattern pointing to the parameters file of the Azure Resource Manager template.

• Template URI (templateUri): The URI to the Azure Resource Manager template.

• Template Parameters (templateParametersUri): The URI to the parameters file of the Azure Resource Manager template.

• Additional What-If Arguments (additionalWhatIfArguments): Additional arguments for what-if operation.

  As mentioned earlier, the task acts as a facade for Azure CLI, translating your input parameters to Azure CLI commands. You can provide additional what-if arguments to override existing arguments or to include arguments not exposed via task input parameters. This option is added to increase flexibility and to potentially allow scenarios not officially supported by the task. Use this option with caution!

  Use these resources for reference: Management Group scope, Subscription scope, Resource Group scope.

  These arguments can not be overridden: --no-pretty-print, --no-prompt, --result-format=FullResourcePayloads.

  Tip: Use --parameters argument to override template parameters. Example: --parameters exampleString='inline string' exampleArray='("value1", "value2")' or --parameters https://mysite/params.json

  Tip: Use --exclude-change-types argument to exclude certain change types from what-if results. Example: --exclude-change-types Ignore NoChange

License

ARM Deployment Insights is licensed under the MIT License.

Support

We are here to help you, but please be aware that no official support is provided.

Limitations & Known Issues

• Icons for the most commonly used and popular resource types have been added. However, even though there are close to 200 icons included in the extension, not every resource type is covered because there are too many of them and there is no official source. The default icon will be displayed as a fallback if a specific resource type icon is missing.

  All icons have been sourced from the Azure Icon Collection provided by Ben Coleman.

• ARM Deployment Insights extension relies on what-if operation results. If you think there is an issue with the results you are getting, please run the what-if operation manually (outside of the ARM Deployment Insights extension) and check if you are getting the same results. There are cases when what-if thinks a resource property will be changed (most often deleted) when in fact no change will occur. This is called noise.

  If you notice incorrect results from the what-if operation, please report the issues at https://aka.ms/whatifissues.

Contact

We can help your organization digitally transform your business and build new software solutions. You can find us at www.authoritypartners.com.

Already have a project you’d like to work together on? Drop us a note at hello@authoritypartners.com, we’re happy to answer all your questions.