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 withresourceId(), which turns a type and a name into the full/subscriptions/.../providers/...id. Inside one template a resource that references another withreference()orlistKeys()gets the dependency implicitly; anything else needsdependsOn, or you get the classic intermittent failure "ParentResourceNotFound" or "the NIC does not exist" on one run out of five.copy- a loop.countsays how many,copyIndex()is the current index (from 0), so one resource block becomes one container per entry of thecontainersparameter.
$ 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.
| function | what it gives |
|---|---|
parameters('x'), variables('x') | an input, a computed value |
resourceGroup().location, resourceGroup().id, subscription().subscriptionId | where 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].value | runtime 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:
| symbol | change type | meaning |
|---|---|---|
+ | Create | not there yet, will be created |
- | Delete | will be deleted (Complete mode only) |
~ | Modify | exists, these properties change (old => new) |
= | NoChange | exists and matches the template |
* | Ignore | in the group but not in the template: left alone (Incremental) |
! | Deploy | will be redeployed, changes unknown |
x | NoEffect / Unsupported | what-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
conditionthat evaluates to false is still deleted in Complete mode; - locks still apply: a
CanNotDeletelock makes the Complete deployment fail rather than delete; - always run
what-if --mode Completefirst, oraz 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:
| scope | command | typical content |
|---|---|---|
| resource group | az deployment group create -g RG | resources |
| subscription | az deployment sub create -l westeurope | resource groups, policy assignments, role assignments |
| management group | az deployment mg create -m MG -l ... | policy definitions, assignments |
| tenant | az 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 NAMEreturns 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."