ARM Templates and Bicep: AZ-104 Deployment Guide

Infrastructure as code means describing the Azure resources you want in a text file and letting Azure Resource Manager create them, rather than building each resource by hand in the portal. The file is declarative: you state the desired end result and Resource Manager works out the order and the API calls needed to reach it.

There are two authoring formats. An ARM template is a JSON file. A Bicep file is a purpose-built language that is easier to read and write; when you deploy it, the Bicep tooling transpiles it into an ordinary ARM template, so Resource Manager still receives JSON. Bicep is a different authoring language, not a different engine, and it has no state file of its own: the current state is whatever exists in Azure.

Both formats are idempotent: deploying the same unchanged file to the same target again succeeds and leaves resources that already match the template unchanged. That is why templates are safe to run on a schedule or in every pipeline run. Idempotent does not mean "never changes anything" — if someone changed a declared property by hand, the redeploy puts it back (see Modifying an existing template).

An ARM template is a JSON object whose top-level elements each have one job. Only three are required: $schema (the version of the template language), contentVersion (your own version stamp) and resources (what to deploy). Everything else is optional:

Values are made dynamic with template expressions in square brackets, such as [parameters('vmName')], [resourceGroup().location] or [concat(variables('prefix'), 'stg')]. Reading a template means tracing a value from a parameter, through a variable, into a resource property and out through an output.

Runtime functions and where they are allowed

Some functions read a resource's runtime state: reference() (properties such as a storage account's endpoints) and the list*() functions (such as listKeys()). Their values only exist during the deployment, so they can be used only in resource properties and in outputs — not in variables, parameter defaults or resource names. Validation rejects a variable that calls reference(); the fix is to put the expression directly in the property and the output that need it.

A resource with a condition that evaluates to false is simply not deployed. Any reference() to it elsewhere (for example in an output) still runs and fails, because the resource does not exist. Guard it with the same test, for example [if(parameters('deployPublicIp'), reference(...).ipAddress, '')].

Resources in ARM JSON are ordered with dependsOn. If a property refers to another resource only through a resourceId() string, Resource Manager does not know about the dependency and may deploy the two in parallel; add dependsOn so the dependent waits.

A Bicep file declares the same parameters, variables, resources and outputs as an ARM template, with less ceremony. It still uses braces for objects, square brackets for arrays and single quotes for strings; the gain is that expressions are written plainly instead of inside bracketed JSON template expressions, and strings use interpolation — '${prefix}stg' instead of [concat(...)].

param location string = resourceGroup().location
@secure()
param adminPassword string
var storageName = '${uniqueString(resourceGroup().id)}stg'

resource stg 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  name: storageName
  location: location
  sku: { name: 'Standard_LRS' }
  kind: 'StorageV2'
}

output blobEndpoint string = stg.properties.primaryEndpoints.blob

Every resource has a symbolic name (stg above) used to refer to it elsewhere in the file. Referencing a symbolic name — stg.id, vnet1.properties.subnets[0].id — creates an implicit dependency, so Resource Manager deploys the referenced resource first. Building the same ID as a string with resourceId(...) creates no dependency; either switch to the symbolic reference or add an explicit dependsOn: [ vnet1 ].

To use a resource the deployment must not create or change, declare it with the existing keyword. If it lives elsewhere, give it a scope: resource hub 'Microsoft.Network/virtualNetworks@2024-05-01' existing with name: 'vnet-hub' and scope: resourceGroup('rg-network'). An existing declaration is read-only; it lets you read properties such as a subnet ID without redeploying the resource.

Outputs return values that only exist after deployment, such as a public IP's FQDN, to the caller or a pipeline. The editor tooling adds type checking and IntelliSense, so many mistakes surface before you deploy.

Both formats deploy the same resources through Azure Resource Manager, so the choice is about authoring experience, not capability.

Anything you can express in an ARM template you can express in Bicep. Microsoft recommends Bicep for new work while ARM JSON stays fully supported, and you can convert between them (see the last section).

Modifying a template usually means changing a value, adding a resource, or redeploying an edited file — and each has a behaviour you need to predict.

Changing values: parameter files

Keep one template and supply environment-specific values separately instead of editing the template per environment. ARM templates use a JSON parameter file (for example azuredeploy.parameters.json); Bicep can use the same JSON format or a .bicepparam file whose using statement names the Bicep file. One parameter file per environment, passed at deployment time, is the least-effort pattern; individual values can also be overridden on the command line (--parameters vmSize=Standard_D4s_v5).

Secrets

• @secure() (or securestring in ARM JSON) is what keeps a parameter's value out of the deployment history and logs. Supplying the value from a parameter file or adding @description() does not hide it.
• Key Vault reference in a JSON parameter file: the parameter value is a reference to the vault's resource ID and secret name. It works only if the vault has enabledForTemplateDeployment set to true (off by default) and the identity running the deployment holds Microsoft.KeyVault/vaults/deploy/action on the vault (Owner and Contributor include it). The vault can be in another resource group or subscription, and no access policy or data-plane role on the secret is needed.
• In Bicep, keyVault.getSecret('name') on an existing vault can be used only to pass a value to a module parameter marked @secure() — not directly in a resource property. In a .bicepparam file, use az.getSecret(subscriptionId, resourceGroup, vaultName, secretName). Both rely on the same vault setting and permission.

Adding a resource

Add an entry to the resources array in ARM JSON (with dependsOn where needed), or a new resource block in Bicep that references other resources symbolically.

What a redeploy does to existing resources

When Resource Manager redeploys a resource that is in the template, it reapplies every property the template declares — it does not merge with what is in Azure. Manual drift is reverted: a VM resized in the portal goes back to the size in the file on the next pipeline run. Properties you leave out of a redeployed resource can be reset, which matters most for virtual networks. If subnets are declared as separate virtualNetworks/subnets child resources and the network itself has no subnets property, each redeploy of the network asks Resource Manager to remove its subnets, and once NICs use them the deployment fails because an in-use subnet cannot be deleted. Declare subnets inside the virtual network's subnets property instead.

Bicep repeats, skips and reuses resources with loops, conditions and modules, so one file can describe many similar resources.

• Loops: [for i in range(0, vmCount): { name: 'vm${i}' ... }] deploys one copy per index; change vmCount to change the count. You can also loop over an array: [for app in appList: { ... }]. ARM JSON does the same with the copy element.
• Filtered loops: [for app in appList: if (app.enabled) { ... }] skips items whose condition is false.
• Batching: loop copies deploy in parallel by default. The @batchSize(n) decorator on the resource deploys them n at a time, in sequence — @batchSize(1) is fully serial. Use it when updating everything at once would take a service offline.
• Conditions: resource pip '...' = if (deployPublicIp) { ... } deploys only when true. Anything that reads a conditional resource must handle the case where it was not deployed (for example deployPublicIp ? pip.properties.ipAddress : '').

Modules

A module is another Bicep file called from your file with its own parameters, which is how a team shares a standard definition (a virtual network, a VM baseline) without copying it. At build time modules are compiled into the single ARM template that is deployed. A module can come from:

A module also has its own scope. A file with targetScope = 'subscription' can create a resource group directly, but resources such as a storage account must be deployed at resource-group scope — so you put them in a module and set scope: rg (the new group's symbolic name) or scope: resourceGroup('rg-logs'). One subscription-level command then creates the group and its contents.

The deployment mode decides what happens to resources that already exist in the target resource group but are not in the template. Incremental is the default; Complete must be requested explicitly (--mode Complete).

Scenario: a resource group contains resources A, B and C, and the template defines A, B and D. Incremental mode leaves the group with A, B, C and D; Complete mode deploys D, updates A and B, and deletes C because the template no longer mentions it.

Where Complete mode does not apply

• It is a resource-group deployment feature: subscription-scope deployments do not support it.
• The portal's custom deployment does not offer it; use the CLI, PowerShell or REST.
• Nested and linked templates must use Incremental mode; only the main template can be Complete.
• If the resource group is locked, Complete mode does not delete its resources.
• Microsoft is gradually deprecating Complete mode and recommends deployment stacks instead.

Deployment stacks

A deployment stack (az stack group create, az stack sub create, az stack mg create, or the New-AzResourceGroupDeploymentStack family) deploys a template and remembers which resources it manages. Two settings make it the replacement for Complete mode:

Unlike Complete mode, a stack deletes only resources it created and later dropped — not unrelated resources other people put in the same group.

Three checks run before a deployment changes anything, and each answers a different question.

What-if respects the deployment mode, so in Complete mode it shows the deletions. To preview and approve in one command, use az deployment group create --confirm-with-what-if (-c) or PowerShell's New-AzResourceGroupDeployment -Confirm: the command shows the what-if result and waits for you to confirm before deploying. Every scope has the matching variant (az deployment sub what-if and so on).

A deployment targets one scope, and the scope decides which resource types the template can declare and which command runs it. Bicep files declare it with targetScope (default resourceGroup); ARM JSON uses a scope-specific $schema.

Resource groups themselves can be declared directly only in a subscription-scope deployment; to also fill the new group, use a module scoped to it. A subscription, management-group or tenant deployment needs a location because Resource Manager stores the deployment's metadata there.

Ways to run a resource-group deployment:

• Azure CLI: az deployment group create --resource-group rg --template-file main.bicep --parameters @dev.parameters.json (the CLI builds Bicep for you).
• Azure PowerShell: New-AzResourceGroupDeployment -ResourceGroupName rg -TemplateFile ./azuredeploy.json; Test-AzResourceGroupDeployment only validates.
• Portal: Deploy a custom template lets you paste or load a template, pick the subscription and resource group, and fill in parameters.

Teams share templates in three ways: linked templates, template specs and Bicep modules. They differ in where the template lives and who has to be able to read it.

A linked template is an ARM JSON template that a main template calls through templateLink with a URI. Resource Manager fetches that URI itself, not your client and not under your identity, so your RBAC role on the storage account does not help. A blob in a private container needs a SAS token appended to the URI at deployment time. If the storage account blocks public network access with its firewall, even a SAS token fails, because Resource Manager cannot reach the endpoint.

A template spec is an Azure resource (Microsoft.Resources/templateSpecs) that stores a template with numbered versions. You create one with az ts create --name web-standard --version 2.0 --resource-group rg-specs --template-file main.bicep and deploy a version by its resource ID (az deployment group create --template-spec ..., or a ts: module reference). Access is plain Azure RBAC: a deployer needs Template Spec Reader on the spec (it can sit in another subscription) plus rights to deploy into the target resource group. No storage account or SAS token is involved, and Reader-level access cannot change the spec.

Bicep modules, whether local or from a registry, are compiled into the main template before deployment, so there are no URIs for Resource Manager to fetch.

There are two export paths, and they return different templates.

Exporting from a resource group or from selected resources can produce ARM JSON or Bicep. Saving from deployment history returns ARM JSON only; run az bicep decompile on it if you want Bicep. Exported templates are a starting point, not a finished artifact: values are hard-coded, some resource types are not exported at all (Azure Data Factory, for example), secret values such as a VM administrator password parameter can be missing and must be added by hand, and a single resource-group export is limited to 200 resources.

Converting between formats

Export plus decompile turns a hand-built resource group into an editable Bicep file.