Azure ARM Templates: Declarative, Idempotent Deployments

Every ARM template has the same skeleton: a $schema pointer, a contentVersion for your own change tracking, a parameters block for inputs, a variables block for values derived inside the template, a resources array describing what to build, and an optional outputs block for values you want back after the deployment. The excerpt below shows the core pattern, a single storage account whose name is supplied at deploy time:

# template.json (excerpt)

"parameters": { "saName": { "type": "string" } },
"resources": [{
  "type": "Microsoft.Storage/storageAccounts",
  "apiVersion": "2023-01-01",
  "name": "[parameters('saName')]",
  "location": "[resourceGroup().location]",
  "sku": { "name": "Standard_LRS" },
  "kind": "StorageV2"
}]

Expected output:

$ az deployment group validate --resource-group tyf-rg --template-file template.json --parameters parameters.dev.json && echo VALID
VALID

Notice the bracket syntax: anything wrapped in [...] is a template expression evaluated by ARM, not a literal string. [parameters('saName')] reads the input, and [resourceGroup().location] makes the resource inherit the location of whatever group it lands in, one less value to hardcode, and one less way for environments to drift apart.

Here is the complete template used for the rest of this lab. It adds input validation (storage account names must be 3-24 characters, lowercase letters and numbers only), a variable for tags, and an output so the deployment hands you back the resource ID:

FULL TEMPLATE, template.json

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "saName": {
      "type": "string",
      "minLength": 3,
      "maxLength": 24,
      "metadata": {
        "description": "Globally unique storage account name, lowercase letters and numbers only."
      }
    },
    "environment": {
      "type": "string",
      "defaultValue": "dev",
      "allowedValues": [ "dev", "test", "prod" ]
    }
  },
  "variables": {
    "commonTags": {
      "deployedBy": "arm-template",
      "environment": "[parameters('environment')]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2023-01-01",
      "name": "[parameters('saName')]",
      "location": "[resourceGroup().location]",
      "tags": "[variables('commonTags')]",
      "sku": { "name": "Standard_LRS" },
      "kind": "StorageV2",
      "properties": {
        "allowBlobPublicAccess": false,
        "minimumTlsVersion": "TLS1_2",
        "supportsHttpsTrafficOnly": true
      }
    }
  ],
  "outputs": {
    "storageAccountId": {
      "type": "string",
      "value": "[resourceId('Microsoft.Storage/storageAccounts', parameters('saName'))]"
    }
  }
}

Environment-specific values belong in a separate parameters file, not in the template. That way the same template.json deploys to dev, test, and prod with only the parameter file changing, which is exactly how pipelines promote infrastructure between environments.

PARAMETER VALUES, parameters.dev.json

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "saName": { "value": "tyfstore01" },
    "environment": { "value": "dev" }
  }
}

What this teaches: Parameters separate inputs from structure, so one template serves every environment instead of one template per environment.

what-if shows exactly what will change before anything is created or modified. Before previewing, though, run a validation pass: az deployment group validate asks ARM to parse the template, resolve expressions, and check parameter values against their constraints, all without touching the resource group. It catches schema errors and bad input far earlier than a failed deployment does.

VALIDATE THE TEMPLATE (no changes made)

az deployment group validate \
  --resource-group tyf-rg \
  --template-file template.json \
  --parameters parameters.dev.json

Expected output:

Resource and scope                       Change
storageAccounts/tyfsademo001             Create

1 resource would change.

Now the preview. what-if compares your template against the live state of the resource group and reports a symbol per resource: + create, ~ modify, - delete, = no change. Read every line of this output as if you were reviewing a diff in a pull request, because that is exactly what it is.

Note that the CLI accepts parameter values inline (saName=tyfstore01) as above, or from a file with --parameters parameters.dev.json as in the validate call. For anything beyond a quick experiment, prefer the file, it is reviewable and committed to source control.

What this teaches: The what-if diff is the safety net: reading a preview before deploying is how you catch destructive changes while they are still cheap.

The create command is the same shape as what-if, minus the preview. Giving the deployment an explicit --name is optional (the CLI derives one from the template file name), but a meaningful name pays off later when you are paging through deployment history in the resource group. ARM runs in Incremental mode by default: it creates and updates what the template describes and leaves everything else in the group alone. The alternative, Complete mode, deletes anything in the group that is not in the template, powerful, and dangerous enough that you should only use it deliberately.

The full response is a large JSON document describing the finished deployment. Two fields matter most: properties.provisioningState tells you the outcome, and properties.outputs contains whatever your template's outputs block computed, here, the resource ID of the new storage account.

Expected output:

{
  "name": "template-001",
  "properties": {
    "provisioningState": "Succeeded",
    "outputs": {
      "storageAccountId": {
        "value": "/subscriptions/.../resourceGroups/tyf-rg/providers/Microsoft.Storage/storageAccounts/tyfsademo001"
      }
    }
  }
}

What this teaches: Deployments are asynchronous ARM operations; the CLI returns once the operation is accepted, and provisioningState tells you when it truly finished.

Never trust a deployment you have not inspected. List what is actually in the resource group, then query the specific resource for the properties the template was supposed to set. This is where you confirm the security-relevant settings, TLS floor, public access disabled, really applied and were not silently ignored.

LIST RESOURCES AND CHECK KEY PROPERTIES

az resource list --resource-group tyf-rg --output table

az storage account show \
  --name tyfstore01 \
  --resource-group tyf-rg \
  --query "{name:name, location:location, sku:sku.name, tls:minimumTlsVersion, publicAccess:allowBlobPublicAccess, tags:tags}"

Expected output:

$ az storage account show -n tyfsademo001 -g tyf-rg --query "{name:name, state:provisioningState, location:primaryLocation}" -o table
Name           State      Location
-------------  ---------  ----------
tyfsademo001   Succeeded  eastus

What this teaches: Every deployment writes to the activity log, which is where you audit who changed what and when.

This is the step that separates declarative infrastructure from scripting. Run the exact same deployment command a second time. ARM compares the template to the live state, finds nothing to change, and returns success without modifying the resource. The deployment succeeds; the work performed is zero.

RE-RUN THE SAME DEPLOYMENT

az deployment group create \
  --resource-group tyf-rg \
  --name storage-deploy-02 \
  --template-file template.json \
  --parameters parameters.dev.json \
  --query properties.provisioningState

Expected output:

$ az deployment group what-if --resource-group tyf-rg --template-file template.json --parameters parameters.dev.json
0 resources would change. The deployment is idempotent.

Idempotency is what makes templates safe to put in a pipeline: a scheduled or triggered re-run converges the environment toward the template rather than duplicating resources or erroring on things that already exist. The formal proof comes in the next section, where what-if reports zero changes.

What this teaches: Idempotency is the core promise of declarative IaC: re-running a template should converge, not duplicate.