OnCallReadyStart learning

Azure Lesson 33.1 · Azure V: Compute, App Hosting & the AZ-104 exam · 30 min read

ARM templates: read, change, preview, deploy, export

In plain words

An ARM template is a shopping list for Azure written in JSON: "one storage account called this, in that region, with these settings". You hand the list to Azure Resource Manager and it makes the resource group look like the list says.

Parameters are the blanks on the list you fill in each time (dev or prod), variables are notes you work out from them, and functions like format() or if() do the working out. What-if lets you see what the shop assistant would change before you pay.

ARM templates: read, change, preview, deploy, export

Every way you change Azure - a click in the portal, an az command, a Terraform apply, a pipeline - ends up as a request to the same front door: Azure Resource Manager (ARM). ARM also has its own language for describing what a resource group should contain, the ARM template: a JSON file you hand to ARM, which works out the order, creates or updates every resource in it and records the result as a deployment. The course deploys with Terraform, and most teams do. You still meet ARM templates every week: the "Export template" button in the portal produces one, Azure Quickstart samples are ARM, vendors ship them, Bicep (next lesson) compiles to them, and AZ-104 expects you to read one, change it and deploy it without help.

Need to know: a template has parameters (inputs), variables (values computed once), resources (what to deploy, each with a type, an apiVersion and a name) and outputs. Any string in square brackets is an expression: [parameters('env')], [resourceGroup().location], [uniqueString(resourceGroup().id)]. az deployment group create -g RG -f file.json -p name=value deploys it to a resource group; what-if shows what would change first. Deployments are Incremental by default: what is in the group but not in the template is left alone. Complete mode deletes it. az group export captures what a group contains now as a template - a starting point, never a finished file.

A template, section by section

The lab folder has a small one: a storage account for the reporting team plus its containers.

$ cd ~/oncall-lab/labs/4b-azure/az5/arm
$ ls
storage.json  storage.prod.parameters.json
$ jq 'keys' storage.json
[
  "$schema",
  "contentVersion",
  "outputs",
  "parameters",
  "resources",
  "variables"
]

$schema and contentVersion are boilerplate (the schema says "a resource group deployment"; contentVersion is yours to bump). The four sections that matter:

$ jq '.parameters' storage.json
{
  "env": {
    "type": "string",
    "allowedValues": [
      "dev",
      "prod"
    ],
    "defaultValue": "dev",
    "metadata": {
      "description": "Which environment this account serves"
    }
  },
  "location": {
    "type": "string",
    "defaultValue": "[resourceGroup().location]"
  },
  "containers": {
    "type": "array",
    "defaultValue": [
      "reports",
      "exports"
    ]
  }
}

Parameters are the inputs. Each has a type (string, securestring, int, bool, object, secureObject, array), and optionally a defaultValue, allowedValues, minLength/maxLength, minValue/maxValue and a metadata.description the portal shows as help text. A parameter without a default must be supplied. allowedValues is checked before anything is created: the deployment is refused, not half done. securestring values are never written to the deployment history - use them for passwords, never string.

$ jq '.variables' storage.json
{
  "name": "[format('st{0}{1}', parameters('env'), uniqueString(resourceGroup().id))]",
  "sku": "[if(equals(parameters('env'), 'prod'), 'Standard_ZRS', 'Standard_LRS')]"
}

Variables are computed inside the template and cannot be set by the person deploying. Here the account name is built once and reused: format('st{0}{1}', ...) glues st, the environment and uniqueString(resourceGroup().id). That last one matters: uniqueString() is a hash, 13 characters, deterministic. The same resource group always gives the same string, so redeploying updates the same account instead of creating a new one, and another group gets another name - which you need, because storage account names are global across all of Azure. The SKU uses if() and equals(): zone-redundant storage in prod, locally redundant elsewhere.

$ jq '.resources[] | {type, apiVersion, name, dependsOn, copy}' storage.json
{
  "type": "Microsoft.Storage/storageAccounts",
  "apiVersion": "2023-05-01",
  "name": "[variables('name')]",
  "dependsOn": null,
  "copy": null
}
{
  "type": "Microsoft.Storage/storageAccounts/blobServices/containers",
  "apiVersion": "2023-05-01",
  "name": "[format('{0}/default/{1}', variables('name'), parameters('containers')[copyIndex()])]",
  "dependsOn": [
    "[resourceId('Microsoft.Storage/storageAccounts', variables('name'))]"
  ],
  "copy": {
    "name": "containerLoop",
    "count": "[length(parameters('containers'))]"
  }
}

Resources each have a type (Microsoft.Storage/storageAccounts), an apiVersion (which version of that resource provider's API the properties follow - an old one can lack a property you need) and a name. A child resource names its parents in both: the container's type is .../storageAccounts/blobServices/containers and its name account/default/reports - one name segment per type segment, or ARM refuses the template with "incorrect segment lengths".

Two more keys on the container:

  • dependsOn - deploy this only after that. ARM deploys everything it can in parallel; it only orders what you tell it to. Here it is built with resourceId(), which turns a type and a name into the full /subscriptions/.../providers/... id. Inside one template a resource that references another with reference() or listKeys() gets the dependency implicitly; anything else needs dependsOn, or you get the classic intermittent failure "ParentResourceNotFound" or "the NIC does not exist" on one run out of five.
  • copy - a loop. count says how many, copyIndex() is the current index (from 0), so one resource block becomes one container per entry of the containers parameter.
$ jq '.outputs' storage.json
{
  "accountName": {
    "type": "string",
    "value": "[variables('name')]"
  },
  "blobEndpoint": {
    "type": "string",
    "value": "[reference(variables('name')).primaryEndpoints.blob]"
  }
}

Outputs are values the deployment returns: here the generated name and the blob endpoint, read with reference() - the resource's runtime state after it is deployed. Pipelines read outputs to pass a name to the next step.

functionwhat it gives
parameters('x'), variables('x')an input, a computed value
resourceGroup().location, resourceGroup().id, subscription().subscriptionIdwhere you deploy
uniqueString(a, b...)a stable 13-character hash of its inputs
concat(a, b), format('{0}-{1}', a, b), toLower(x)strings
resourceId('Type', 'name')a resource's full id (for dependsOn and references)
reference(id).prop, listKeys(id, api).keys[0].valueruntime properties, keys (implicit dependency)
copyIndex(), length(arr)loops
if(cond, a, b), equals(a, b)conditions (also a resource's "condition": bool)
utcNow()the time - only allowed as a parameter's defaultValue

On the exam (AZ-104 3.1.1, 3.1.2): you get a template excerpt and are asked what it deploys, what name a resource will have, why a deployment fails, or which section to change. Read the brackets: a value in square brackets is evaluated, anything else is literal text.

Preview first: what-if

Before deploying anything into a group that already holds resources, ask ARM what it would do:

$ az deployment group what-if -g rg-az5-arm -f storage.json -p env=prod
Note: The result may contain false positive predictions (noise).
You can help us improve the accuracy of the result by opening an issue here: https://aka.ms/WhatIfIssues

Resource and property changes are indicated with these symbols:
  + Create
  * Ignore

The deployment will update the following scope:

Scope: /subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/rg-az5-arm

  + Microsoft.Storage/storageAccounts/stprodm72kia7ilwj5b [2023-05-01]

      apiVersion:                       "2023-05-01"
      id:                               "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/rg-az5-arm/providers/Microsoft.Storage/storageAccounts/stprodm72kia7ilwj5b"
      kind:                             "StorageV2"
      location:                         "westeurope"
      name:                             "stprodm72kia7ilwj5b"
      properties.allowBlobPublicAccess: false
      properties.minimumTlsVersion:     "TLS1_2"
      sku.name:                         "Standard_ZRS"
      tags.env:                         "prod"
      tags.owner:                       "platform"
      type:                             "Microsoft.Storage/storageAccounts"

  + Microsoft.Storage/storageAccounts/stprodm72kia7ilwj5b/blobServices/default/containers/exports [2023-05-01]

      apiVersion:              "2023-05-01"
      id:                      "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/rg-az5-arm/providers/Microsoft.Storage/storageAccounts/stprodm72kia7ilwj5b/blobServices/default/containers/exports"
      name:                    "stprodm72kia7ilwj5b/default/exports"
      properties.publicAccess: "None"
      type:                    "Microsoft.Storage/storageAccounts/blobServices/containers"

  + Microsoft.Storage/storageAccounts/stprodm72kia7ilwj5b/blobServices/default/containers/reports [2023-05-01]

      apiVersion:              "2023-05-01"
      id:                      "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/rg-az5-arm/providers/Microsoft.Storage/storageAccounts/stprodm72kia7ilwj5b/blobServices/default/containers/reports"
      name:                    "stprodm72kia7ilwj5b/default/reports"
      properties.publicAccess: "None"
      type:                    "Microsoft.Storage/storageAccounts/blobServices/containers"

  * Microsoft.Storage/storageAccounts/streportsmanual01

Resource changes: 3 to create, 1 to ignore.

The legend lists only the change types that occur. The full set:

symbolchange typemeaning
+Createnot there yet, will be created
-Deletewill be deleted (Complete mode only)
~Modifyexists, these properties change (old => new)
=NoChangeexists and matches the template
*Ignorein the group but not in the template: left alone (Incremental)
!Deploywill be redeployed, changes unknown
xNoEffect / Unsupportedwhat-if cannot tell (for example, a nested template it cannot expand)

Read a Modify line carefully: ~ sku.name: "Standard_LRS" => "Standard_ZRS" is a change of redundancy, which on a storage account is a migration, not a flag. The first line of the output says it plainly: the result "may contain false positive predictions (noise)" - read-only properties and defaults sometimes show as changes. What-if is how you catch the real surprise: a -, or a ~ on something you did not mean to touch.

Deploy, and the deployment history

$ az deployment group create -g rg-az5-arm -f storage.json -p env=prod --query properties.outputs
{
  "accountName": {
    "type": "String",
    "value": "stprodm72kia7ilwj5b"
  },
  "blobEndpoint": {
    "type": "String",
    "value": "https://stprodm72kia7ilwj5b.blob.core.windows.net/"
  }
}
$ az deployment group list -g rg-az5-arm -o table
Name     State      Timestamp                         Mode         ResourceGroup
-------  ---------  --------------------------------  -----------  -------------
storage  Succeeded  2026-09-22T20:00:07.250000+00:00  Incremental  rg-az5-arm
$ az deployment operation group list -g rg-az5-arm -n storage -o table
ProvisioningState  StatusCode  ResourceName                         ResourceType
-----------------  ----------  -----------------------------------  ---------------------------------------------------------
Succeeded          Created     stprodm72kia7ilwj5b                  Microsoft.Storage/storageAccounts
Succeeded          Created     stprodm72kia7ilwj5b/default/reports  Microsoft.Storage/storageAccounts/blobServices/containers
Succeeded          Created     stprodm72kia7ilwj5b/default/exports  Microsoft.Storage/storageAccounts/blobServices/containers

The deployment's name defaults to the file name (storage); pass -n to choose one, and a second deployment with the same name replaces the first in the history. The history keeps up to 800 deployments per resource group; ARM deletes the oldest ones automatically as you approach the limit. deployment operation group list is the first thing to read when a deployment fails: one row per resource, with its status code and the error of the one that broke (az deployment group show only says "At least one resource deployment operation failed").

Run the same deployment again and nothing changes - ARM deployments are idempotent (a PUT of the same desired state). That is why uniqueString() and not utcNow() makes names.

Parameters can come from a parameter file instead of the command line. Its shape is fixed: {"$schema": ..., "parameters": {"env": {"value": "prod"}}}. Pass it with -p @file.json (or just -p file.json) and override single values after it - the later -p wins:

$ jq . storage.prod.parameters.json
{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "env": {
      "value": "prod"
    },
    "containers": {
      "value": [
        "reports",
        "exports"
      ]
    }
  }
}
$ az deployment group what-if -g rg-az5-arm -f storage.json -p @storage.prod.parameters.json -p containers='["reports","exports","audit"]'
Note: The result may contain false positive predictions (noise).
You can help us improve the accuracy of the result by opening an issue here: https://aka.ms/WhatIfIssues

Resource and property changes are indicated with these symbols:
  + Create
  = Nochange
  * Ignore

The deployment will update the following scope:

Scope: /subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/rg-az5-arm

  + Microsoft.Storage/storageAccounts/stprodm72kia7ilwj5b/blobServices/default/containers/audit [2023-05-01]

      apiVersion:              "2023-05-01"
      id:                      "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/rg-az5-arm/providers/Microsoft.Storage/storageAccounts/stprodm72kia7ilwj5b/blobServices/default/containers/audit"
      name:                    "stprodm72kia7ilwj5b/default/audit"
      properties.publicAccess: "None"
      type:                    "Microsoft.Storage/storageAccounts/blobServices/containers"

  = Microsoft.Storage/storageAccounts/stprodm72kia7ilwj5b [2023-05-01]
  = Microsoft.Storage/storageAccounts/stprodm72kia7ilwj5b/blobServices/default/containers/exports [2023-05-01]
  = Microsoft.Storage/storageAccounts/stprodm72kia7ilwj5b/blobServices/default/containers/reports [2023-05-01]
  * Microsoft.Storage/storageAccounts/streportsmanual01

Resource changes: 1 to create, 3 no change, 1 to ignore.

One container to create, the rest unchanged: that is what a reviewer wants to see in a PR.

Incremental vs Complete

Incremental (the default) creates and updates what the template lists and leaves everything else in the group alone - the * Ignore lines you saw for streportsmanual01. Complete makes the group match the template: anything in it that the template does not list is deleted. It exists for groups that are fully owned by one template; anywhere else it is the fastest way to delete a colleague's database. Someone created that account by hand last month:

$ az storage account list -g rg-az5-arm --query "[].name" -o tsv
streportsmanual01
stprodm72kia7ilwj5b
$ az deployment group what-if -g rg-az5-arm -f storage.json -p @storage.prod.parameters.json --mode Complete
Note: The result may contain false positive predictions (noise).
You can help us improve the accuracy of the result by opening an issue here: https://aka.ms/WhatIfIssues

Resource and property changes are indicated with these symbols:
  - Delete
  = Nochange

The deployment will update the following scope:

Scope: /subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/rg-az5-arm

  - Microsoft.Storage/storageAccounts/streportsmanual01
  = Microsoft.Storage/storageAccounts/stprodm72kia7ilwj5b [2023-05-01]
  = Microsoft.Storage/storageAccounts/stprodm72kia7ilwj5b/blobServices/default/containers/exports [2023-05-01]
  = Microsoft.Storage/storageAccounts/stprodm72kia7ilwj5b/blobServices/default/containers/reports [2023-05-01]

Resource changes: 1 to delete, 3 no change.

The hand-made account is a -. In Complete mode it would be gone, with its data. Rules worth remembering:

  • Complete mode exists only at resource group scope;
  • a resource excluded by a condition that evaluates to false is still deleted in Complete mode;
  • locks still apply: a CanNotDelete lock makes the Complete deployment fail rather than delete;
  • always run what-if --mode Complete first, or az deployment group create --mode Complete --confirm-with-what-if (-c): it prints the what-if and asks before deploying.

Scopes

az deployment group deploys into a resource group. Templates can target other scopes, each with its own schema and command:

scopecommandtypical content
resource groupaz deployment group create -g RGresources
subscriptionaz deployment sub create -l westeuroperesource groups, policy assignments, role assignments
management groupaz deployment mg create -m MG -l ...policy definitions, assignments
tenantaz deployment tenant create -l ...management groups

A subscription deployment needs --location: not where resources go, but where ARM stores the deployment's metadata.

Export: from what exists to a template

Two different exports, often confused:

  • az deployment group export -g RG -n NAME returns the template a past deployment used - parameters, expressions and all. Useful when you need to redeploy "what we deployed in March".
  • az group export -n RG (the portal's Export template on a resource group) captures the current state of the resources as a new template.
$ az group export -n rg-az5-arm > exported.json
$ jq '.parameters | keys' exported.json
[
  "storageAccounts_stprodm72kia7ilwj5b_name",
  "storageAccounts_streportsmanual01_name"
]
$ jq '.resources[0] | {name, sku, properties: (.properties | keys)}' exported.json
{
  "name": "[parameters('storageAccounts_stprodm72kia7ilwj5b_name')]",
  "sku": {
    "name": "Standard_ZRS"
  },
  "properties": [
    "accessTier",
    "allowBlobPublicAccess",
    "allowSharedKeyAccess",
    "encryption",
    "minimumTlsVersion",
    "primaryEndpoints",
    "publicNetworkAccess",
    "supportsHttpsTrafficOnly"
  ]
}

Look at what you got: every resource name became a parameter with an ugly generated name (storageAccounts_stprod..._name), every other value is hard-coded (the location, the SKU), and the properties include values Azure fills in (endpoints, defaults) that you never set. No variables, no loops, no uniqueString(). Some resource types cannot be exported at all, and the export says so in a warning. Treat an exported template as notes about what exists: copy the resources you need into a clean template, replace hard-coded values with parameters, delete read-only properties, and what-if it against the real group until it says = everywhere. The next lesson does exactly that, in Bicep, with az bicep decompile.

On the exam (AZ-104 3.1.4, 3.1.5): "deploy a template with a parameter file" = az deployment group create -f template.json -p @params.json (PowerShell: New-AzResourceGroupDeployment -TemplateFile -TemplateParameterFile); "the template used by an earlier deployment" = export the deployment; "the current configuration of a group" = export the resource group. Questions about deleting resources not in the template are about Complete mode.

In an interview: "What is the difference between Incremental and Complete deployments?" - "Incremental, the default, creates and updates what the template lists and leaves everything else in the resource group alone. Complete makes the group match the template and deletes what is not in it - so I only use it on groups one template owns, and always after a what-if."

Why it helps

Clicking in the portal does not repeat: the second environment is never quite the same as the first. A template does, and it is reviewable in a pull request. AZ-104 expects you to read a template, change it, deploy it with a parameter file and export one from what exists.

The dangerous part is the mode. Incremental leaves extra resources alone; Complete deletes them. Reading a what-if before a Complete deployment is the habit that prevents a deleted production database.

Commands in this lesson

cd ls jq az

FAQ

What are the sections of a template?

$schema and contentVersion (fixed values), parameters (inputs, with type, defaultValue and allowedValues), variables (values computed once), resources (each with type, apiVersion, name, location and properties), and outputs (values returned after the deployment, like the account name). Functions such as resourceGroup().location and uniqueString() fill in values at deployment time.

What does what-if show?

Every resource the deployment would touch, with a symbol: + Create, ~ Modify (with the properties that change), - Delete (only in Complete mode), = NoChange, * Ignore. The last line counts them. It evaluates the whole template against the real resource group, so the names and values it shows are the ones that would be deployed.

Where do I see what a deployment did?

Every deployment is kept by name in the resource group: az deployment group list and show give its state, parameters and outputs, and az deployment operation group list shows each resource operation and the error of the one that failed. Re-running a deployment with the same name replaces that entry; the default name is the template file name.

Can I export a template from the portal or CLI?

Yes: az group export (or "Export template" in the portal) writes the resource group's current resources as a template. It is a starting point, not a finished template: names and values are hard-coded, some properties are missing or read-only, and you add parameters before reusing it. Deployments you ran can also be saved with az deployment group export.

Templates can deploy at which scopes?

A resource group (az deployment group create), a subscription (az deployment sub create, for resource groups and policy), a management group (az deployment mg create) and the tenant (az deployment tenant create). Most resource templates are resource-group scoped; the scope also decides where the deployment history is kept.

In an interview Mid

What is the difference between Incremental and Complete deployments?

Incremental, the default, creates and updates what the template lists and leaves everything else in the resource group alone. Complete makes the group match the template and deletes what is not in it. I only use Complete on a group that one template owns, and always after az deployment group what-if with --mode Complete - the - lines are exactly what would be deleted.

Also asked: How do you pass different values for dev and prod to the same template? · What does uniqueString() return and why is it useful for names? · How do you find out why a template deployment failed?

Practise this lesson in the terminal Free, in your browser - a real Ubuntu terminal to try it in, with missions that check your work.