Working with ARM Template Deployment Modes

Azure Resource Manager (or ARM) templates provide a way for you to describe Azure resources using code. There are also two different ARM template deployment modes: incremental and complete. Both deployment modes provide different capabilities, with one being more destructive than the other.

In this post, you will learn:

• How to deploy ARM templates using PowerShell
• The differences between the different ARM template

Deploying ARM Templates Using PowerShell

Azure provides two options for ARM template deployment modes: incremental and complete. This blog post will cover the difference between the two using an ARM template to deploy a virtual network using the Azure PowerShell module.

You target Azure Resource Manager (ARM) templates deployments to subscriptions or resource groups. Using JSON formatted files, you deploy Azure resources such as networks, virtual machines, storage accounts, really just about any resource.

However, you also use ARM templates as a way to validate a deployment after its initial use. The ARM template is standard for how Azure should configure the environment. If a resource is accidentally deleted, you can use the same ARM template to deploy the resource again.

Here’s an ARM template to deploy a virtual network name vnetA using the address space 192.168.1.0/24:

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "resources": [
        {
            "name": "vnetA",
            "type": "Microsoft.Network/virtualNetworks",
            "apiVersion": "2019-09-01",
            "location": "centralus",
            "properties": {
                "addressSpace": {
                    "addressPrefixes": [
                        "192.168.1.0/24"
                    ]
                }
            }
        }
    ]
}

Use the New-AzResourceGroupDeployment and specify the JSON file hosting the ARM template code and deploy to the armdemo resource group:

New-AzResourceGroupDeployment -ResourceGroupName armdemo `
    -TemplateFile .\deploy-vnet.json

And this will successfully deploy the virtual network:

Deploying an ARM Template using Incremental Mode

Next, change the “name” property in the ARM template to “vnetB” as well as the “addressPrefixes” to “192.168.2.0/24”. Re-run my PowerShell deployment command from above, and Azure will perform an incremental deployment.

An incremental deployment deploys any resources to the resource group that don’t exist but leaves any existing ones alone. The resource group ends up with both a vnetA and a vnetB:

To summarize, the incremental mode will deploy any resources defined in the ARM template that don’t already exist but leaves any resources not defined in the ARM template alone. To explicitly use incremental, use -Mode Incremental with the previous command:

New-AzResourceGroupDeployment -ResourceGroupName armdemo `
    -TemplateFile .\deploy-vnet.json `
    -Mode Incremental

Deploying an ARM Template using Complete Mode

If you switch the value from Incremental to Complete, you end up with different behavior. Complete deployment mode will delete any resources that are not defined in the ARM template. If you deploy the same template with just vnetB defined using complete mode, Azure will verify that vnetB is deployed but then remove vnetA since it is not defined in the template.

In fact, you will get a prompt saying that resources not defined will be deleted:

New-AzResourceGroupDeployment -ResourceGroupName armdemo `
    -TemplateFile .\deploy-vnet.json `
    -Mode Complete

Going back to the virtual networks in the portal, only virtual network vnetB remains as vnetA was not defined in the ARM template, therefore Azure deleted it.

Summary

You use incremental mode to make changes to existing resources by specifying the changes in the ARM template but not delete other resources. However, Microsoft’s document recommends always specifying other values for the resource, not just the ones being modified by the template as Resource Manager could end up overwriting those values as well.

Another important point for complete mode is it does not do a complete re-deployment of all the resources; it will just verify the resources defined in the template are already created and remove any resources that are not defined.

Also, note the version of REST API being used. If using a version earlier than 2019-05-10, the resources are not deleted. The complete delete actions are only applied if using a REST API later than 2019-05-10.

Questions or comments? If so, drop me a note below or find me on Twitter or LinkedIn to discuss further.

Reference:

Microsoft Docs: Azure Resource Manager deployment modes

https://docs.microsoft.com/azure/azure-resource-manager/deployment-modes