Domain 3 of 5 · Chapter 1 of 4

Automate deployments with ARM templates and Bicep

From a file to deployed resources

A storage account declared in a template becomes one REST call. When Azure Resource Manager receives the declaration below, it sends the Microsoft.Storage resource provider a PUT request for mystorageaccount, and the apiVersion written in the declaration becomes the API version of that request (What are ARM templates?[1]).

A minimal resource declaration in an ARM template

{
  "type": "Microsoft.Storage/storageAccounts",
  "apiVersion": "2025-06-01",
  "name": "mystorageaccount",
  "location": "centralus",
  "sku": { "name": "Standard_LRS" },
  "kind": "StorageV2"
}

This topic covers how you read, change, deploy and export definitions like this one, written either as an Azure Resource Manager (ARM) template, which is a JSON file, or as a Bicep file. Moving a virtual machine to another resource group, subscription or region, and managing resource groups, subscriptions and Azure Policy themselves, are tasks for other topics, not this one: The Microsoft AZ-104 study guide skills measured[2] lists "Move a virtual machine to another resource group, subscription, or region" under Create and configure virtual machines, and "Manage resource groups", "Manage subscriptions" and "Implement and manage Azure Policy" under Manage Azure subscriptions and governance; see Create and configure virtual machines and Manage Azure subscriptions and governance. Creating a resource group or a policy assignment from a template does belong here, as Deploying across scopes shows.

One engine, two syntaxes

Bicep offers the same capabilities as ARM templates with a syntax that is easier to use, and each Bicep file is automatically converted to an ARM template during deployment (What are ARM templates?[1]). From that point on, the two formats behave identically. Resource Manager validates the template before it starts, so a deployment is less likely to stop in a half-finished state, and it deploys resources in parallel whenever they don't depend on each other (What are ARM templates?[1]). It works out that order by evaluating the dependencies between resources and deploying them in their dependent order (ARM resource dependencies[3]), as Deployment order: implicit and explicit dependencies below describes.

Declarative and idempotent

Both formats are declarative: you state which resources and properties you want, not the sequence of commands that creates them. They are also idempotent: you can deploy the same template many times and get the same resource types in the same state, and if the storage account above already exists with those properties, a redeployment changes nothing (What are ARM templates?[1]).

A redeployment reaches the same resource because of the resource's identity: the target resource group (or other scope) plus the declared type and name. Change a setting while keeping that identity, and Resource Manager updates the existing resource. Change the name, and the declaration identifies a different resource: deploying a storage account named storage1 and then running the same deployment with storage2 leaves two storage accounts (Azure CLI deployment[4]).

Two attributes of an existing resource can't be changed by redeploying it. If you try to update the location or type of an existing resource, the deployment fails with an error; deploy a new resource with the location or type you need instead (deployment modes[5]).

The figure below traces the path from a Bicep file to deployed resources; an ARM template you write directly enters at the second step.

Takeaway: keep a resource's name and target scope stable when you redeploy to change its configuration, and change them only when you want a different resource.

Bicep fileconvertedARM template (JSON)Resource Managervalidates the templateOne REST request perresource, at its apiVersionResource providers createor update the resources
From a Bicep file to deployed resources: conversion to an ARM template, validation, then one REST request per resource

Reading an ARM template

Every ARM template shares one top-level layout, so interpreting a template starts with knowing what each element is for. The listing below is a complete template that deploys one storage account and returns its blob endpoint; later sections reuse it.

A complete ARM template for one storage account (storage.json)

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    }
  },
  "variables": {
    "storageName": "[concat('storage', uniqueString(resourceGroup().id))]"
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2025-06-01",
      "name": "[variables('storageName')]",
      "location": "[parameters('location')]",
      "sku": { "name": "Standard_LRS" },
      "kind": "StorageV2"
    }
  ],
  "outputs": {
    "blobEndpoint": {
      "type": "string",
      "value": "[reference(variables('storageName')).primaryEndpoints.blob]"
    }
  }
}

Three version elements with three different jobs

Element What it controls
$schema The JSON schema file that describes the version of the template language. Which file you use depends on the deployment scope: the listing uses the resource group file, and subscription, management group and tenant deployments each have their own.
contentVersion Your own version label for the template, such as 1.0.0.0. Any value is accepted; it documents significant changes and can confirm that the right template is being used.
apiVersion (on each resource) The version of the REST API used to create that resource. Keep it stable while the template works, and update it when you need a feature introduced in a later version.

All three are defined in the ARM template structure reference[6]. The practical consequence: when a property you want to set only exists in a newer resource-provider API, change that resource's apiVersion. Raising contentVersion only relabels your template and enables nothing in Azure.

The parameters, variables, resources and outputs elements

  • parameters: values supplied when the deployment runs, so the same template can be customized for different environments. An expression reads one with parameters('location').
  • variables: values the template constructs for reuse, often from parameters, such as the generated storageName. An expression reads one with variables('storageName'). Nobody can pass a variable in at deployment time, because a parameter file may contain values only for parameters the template defines (parameter files[7]).
  • resources: the resources to deploy or update. It is required, like $schema and contentVersion.
  • outputs: values returned after deployment, typically from deployed resources, such as an endpoint a later step needs. An output returns a value; it creates nothing. In the listing, reference(variables('storageName')) returns an object representing the deployed storage account's runtime state (ARM resource functions[8]), and the output reads primaryEndpoints.blob from it.

The element list and roles come from the ARM template structure reference[6], which also describes the less common optional elements languageVersion, apiProfile, definitions and functions (user-defined functions).

Inside a resource declaration

A resource combines the required type (resource provider namespace plus resource type, such as Microsoft.Storage/storageAccounts), apiVersion and name with resource-specific settings such as location, sku, kind and properties. The values in properties are the same ones you would send in the request body of the REST API PUT operation (ARM template structure[6]).

In the listing, the storage account's region comes from the location parameter, whose default value is the expression [resourceGroup().location]. The account follows the resource group's region only because that default asks for it, and only when the caller supplies no other value; a default is used only when no value is provided (ARM template parameters[9]).

languageVersion 2.0 and symbolic names

Adding "languageVersion": "2.0" lets a template declare resources as an object keyed by symbolic names instead of as an array, the same idea Bicep uses (ARM template structure[6]):

The resources element under languageVersion 2.0

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "resources": {
    "stg": {
      "type": "Microsoft.Storage/storageAccounts",
      ...
    }
  }
}

With 2.0, the symbolic name stg can be used in dependsOn arrays (the explicit list of resources that must deploy first; see Deployment order: implicit and explicit dependencies below) and in the reference function, and the template can use type definitions and aggregate validation constraints that check object properties and array elements (ARM template structure[6]). The language version is a template-level setting: updating a resource's apiVersion selects a newer REST API for that resource and does not turn on any template-language feature.

Takeaway: $schema and languageVersion describe the template language, contentVersion is your own label, and each resource's apiVersion picks the REST API that resource is created with.

Template expressions and functions

A string in square brackets is not text in an ARM template: Resource Manager evaluates it as an expression when the template is deployed, and the result can be a string, integer, boolean, array or object (ARM template expressions[10]). The storageName variable from the previous listing is a typical example.

The name expression from storage.json

"storageName": "[concat('storage', uniqueString(resourceGroup().id))]"

Read it from the inside out, because the arguments of a nested function are evaluated before the function that receives them:

  1. resourceGroup() calls a template function that returns an object describing the resource group being deployed to, and .id takes one property of that object, the group's resource ID (ARM template expressions[10]).
  2. uniqueString(...) turns that ID into a 13-character hash. The result isn't random: it comes from a hash function, so the same inputs always produce the same value, and the inputs you choose set how far the uniqueness reaches, such as per subscription or per resource group (ARM string functions[11]).
  3. concat('storage', ...) joins the literal prefix to the hash. Inside an expression, a literal string uses single quotes (ARM template expressions[10]).

[format('{0}{1}', 'storage', uniqueString(resourceGroup().id))] builds the same kind of name with numbered placeholders (ARM template structure[6]). Because the hash depends only on the resource group's ID, redeploying to the same group yields the same name, which is what lets a redeployment update the existing account instead of creating another one (see From a file to deployed resources).

Where expressions are evaluated, and where they are not

  • Template values. Expressions in parameter defaults, variables, resource properties and outputs are evaluated at deployment.
  • Literal-only properties. A resource's type and apiVersion, and the names of parameters, variables and outputs, must be literal strings because they have to be known before any expression is evaluated (ARM template expressions[10]).
  • Values you pass in. A value supplied on the command line or in a parameter file is interpreted literally (ARM template expressions[10]). Writing "[concat('storage', uniqueString(resourceGroup().id))]" as a parameter-file value passes that bracketed text to the template, not its result, so compute generated names inside the template, in a variable or a parameter default.
  • Scope-bound functions. resourceGroup() can be used only in deployments to a resource group, and subscription() only in deployments to a resource group or a subscription (ARM template expressions[10]).

Bicep drops the brackets: functions are called directly and strings are built by interpolation, so the same name is written 'storage${uniqueString(resourceGroup().id)}' (Bicep file structure[12]).

Takeaway: inside a template, brackets mean "evaluate at deployment"; values arriving from outside the template are taken literally.

Reading a Bicep file

Here is the storage template from Reading an ARM template rewritten as Bicep. It deploys the same storage account and returns the same output, and later sections reuse it as storage.bicep.

The same storage deployment as a Bicep file (storage.bicep)

param location string = resourceGroup().location

var storageName = 'storage${uniqueString(resourceGroup().id)}'

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

output blobEndpoint string = stg.properties.primaryEndpoints.blob

Matched line by line against the JSON version (Bicep file structure[12]):

  • param location string = resourceGroup().location declares a parameter, its type and its default in one line.
  • var storageName = ... declares a variable. Parameters and variables are then used by their bare names (location, storageName), with no parameters() or variables() wrapper and no brackets.
  • resource stg 'Microsoft.Storage/storageAccounts@2025-06-01' joins the resource type and API version with @; stg is the resource's symbolic name.
  • output blobEndpoint string = stg.properties.primaryEndpoints.blob reads a property of the deployed resource through its symbolic name.

Bicep is declarative, so these elements can appear in any order without changing how the deployment is processed (Bicep file structure[12]).

The symbolic name is not the Azure name

A resource's symbolic name isn't the same as its resource name (resource declaration in Bicep[13]). stg exists only inside the file, where other declarations and outputs use it (stg.id, stg.properties...) to refer to the resource. The resource's name in Azure is whatever the name property says. Renaming stg to logStorage changes nothing in Azure, while changing name points the declaration at a different storage account. The same holds for a declaration such as resource vm 'Microsoft.Compute/virtualMachines@2025-04-01': vm is a local handle, and the virtual machine's Azure name comes from its name property.

Reading a resource you don't deploy: existing

When a deployment needs a value from a resource this file doesn't manage, such as the endpoint of a shared logging account, declare that resource with the existing keyword (existing resources in Bicep[14]).

Referencing a storage account in another resource group

resource logs 'Microsoft.Storage/storageAccounts@2025-06-01' existing = {
  name: 'examplestorage'
  scope: resourceGroup('rg-shared')
}

output logsBlobEndpoint string = logs.properties.primaryEndpoints.blob

A resource referenced with existing isn't deployed again, so you supply only its name, plus a scope when it lives in another resource group or subscription. If no resource matches, the deployment fails with a NotFound error, so check the name and scope (existing resources in Bicep[14]). existing never creates a missing resource. Leaving out the existing keyword isn't enough to deploy this account: supply a valid resource definition, and use a module to deploy it to the other resource group (resource-group deployment scopes[15]). A module is a Bicep file (or an ARM template) that another Bicep file deploys (Bicep modules[16]); see Nested and linked templates and Bicep modules and Deploying across scopes below.

Takeaway: in a Bicep file, symbols connect declarations inside the file, the name property decides which Azure resource is affected, and existing reads a resource without taking over its definition.

Declaring parameters in ARM and Bicep

Parameters are the only part of a template that the person deploying it can change, so their declarations form the template's input contract. An ARM template declares each parameter as a JSON object with a type and optional properties. A Bicep file declares the same contract with param, a type, and decorators, which are @name(...) annotations placed on the lines above the declaration (Bicep parameters[17]).

One input contract, ARM version

"parameters": {
  "storageSku": {
    "type": "string",
    "defaultValue": "Standard_LRS",
    "allowedValues": [ "Standard_LRS", "Standard_GRS" ],
    "metadata": { "description": "Redundancy for the storage account." }
  },
  "storagePrefix": {
    "type": "string",
    "minLength": 3,
    "maxLength": 11
  },
  "adminPassword": {
    "type": "securestring"
  }
}

The same contract, Bicep version

@description('Redundancy for the storage account.')
@allowed([
  'Standard_LRS'
  'Standard_GRS'
])
param storageSku string = 'Standard_LRS'

@minLength(3)
@maxLength(11)
param storagePrefix string

@secure()
param adminPassword string

Types and defaults

ARM parameter types are string, securestring, int, bool, object, secureObject and array (ARM template structure[6]). Bicep marks a string or object parameter secure with @secure() instead of using separate secure types (Bicep parameters[17]). A default value is used only when the deployment supplies no value for that parameter (ARM template parameters[9]).

When several values belong together, such as a virtual network's name, address prefixes and subnets, pass them as one object parameter (or an array for a collection) rather than as many separate parameters. That keeps the contract readable and also helps with the limit of 256 parameters per ARM template or Bicep file (ARM template parameters[9], Bicep parameters[17]). Hard-coding an environment-specific value inside a resource declaration does the opposite: the caller can no longer choose it.

Constraints

Constraints make a deployment fail validation, before any resource is touched, when an input is out of range. Each ARM property has a matching Bicep decorator (ARM template structure[6], Bicep parameters[17]):

ARM property Bicep decorator What it enforces
allowedValues @allowed([...]) The value must be one of the listed values.
minValue, maxValue @minValue(), @maxValue() The range of an int; both limits are inclusive.
minLength, maxLength @minLength(), @maxLength() The number of characters in a string or items in an array; both limits are inclusive.
metadata.description @description() Nothing: the text is shown as a tip in the Azure portal.

The last row describes documentation, not validation. A description that says "use Standard_LRS or Standard_GRS" documents the expectation but accepts any value. To actually restrict the SKU, list the permitted values in allowedValues or @allowed; a deployment that passes any other value then fails during validation (ARM template parameters[9]).

Secure parameters

Mark passwords and other sensitive inputs as secure: securestring or secureObject in ARM, @secure() on a string or object parameter in Bicep. Resource Manager doesn't save a secure parameter's value to the deployment history and doesn't log it (ARM template parameters[9], Bicep parameters[17]). @secure() is valid only on strings and objects; to pass an array or a number securely, wrap it in a secure object or serialize it into a secure string (Bicep parameters[17]). Grouping credentials into an ordinary object parameter gives them no protection, because only the secure types are kept out of the history. Where the secret value itself should come from is covered in Passing a secret through a Key Vault reference below.

When defaults are evaluated

Resource Manager resolves parameter values before it starts any deployment operation (ARM template parameters[9]). A default can therefore use an expression such as resourceGroup().location or build on another parameter (param hostingPlanName string = '${siteName}-plan'). It can't call the reference function or any list* function such as listKeys, because those read a resource's runtime state, and it can't use a variable (ARM template parameters[9], Bicep parameters[17]). Put runtime lookups in resource properties or outputs, where that state is available.

Takeaway: types and constraints reject bad input before deployment, a description only documents, the secure types keep values out of history, and defaults can't depend on anything that exists only at run time.

Supplying parameter values at deployment

The template declares the inputs; each deployment supplies them. Values can come from a JSON parameter file, a Bicep parameters file (.bicepparam), or inline name=value pairs on the command line; a JSON parameter file can be combined with inline overrides (Bicep deployment with Azure CLI[18]).

JSON parameter files

A JSON parameter file for a template with storagePrefix and storageAccountType parameters

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "contoso"
    },
    "storageAccountType": {
      "value": "Standard_ZRS"
    }
  }
}

The file is checked against the template's declarations (parameter files[7]):

  • Each entry name must match a parameter declared in the template, and each value must have the declared type and satisfy its constraints, such as allowed values or a maximum length.
  • A parameter with no default must get a value. A parameter with a default may be left out, and a value in the file overrides the default.
  • An entry for a parameter the template doesn't declare causes an error. A parameter file therefore can't set a resource property that the template doesn't expose as a parameter; change the template instead.
  • An entry holds either value (the data itself) or reference, a key that points at a Key Vault secret (see Passing a secret through a Key Vault reference). Despite the shared name, this key isn't the reference template function from Declaring parameters in ARM and Bicep, which reads a deployed resource's runtime state.

The file stores values as plain text, which is why secrets belong in a key vault rather than in the file (parameter files[7]).

Bicep parameters files

A Bicep parameters file (main.prod.bicepparam)

using './main.bicep'

param storagePrefix = 'contoso'
param storageAccountType = 'Standard_ZRS'

The using statement ties the file to its Bicep file, and the parameter types come from that Bicep file, so they aren't repeated (Bicep parameters[17]). Because of using, Azure CLI 2.53.0 or later deploys it with --parameters main.prod.bicepparam and no --template-file; adding --template-file produces the error "Only a .bicep file is allowed with a .bicepparam file" (Bicep deployment with Azure CLI[18]).

Inline values and overrides in Azure CLI

--template-file selects the definition and --parameters supplies the inputs; they are separate arguments. Parameter values are evaluated in order and the last assignment wins, so the recommended pattern is the parameter file first, followed by name=value pairs that override selected entries. A .bicepparam file can be passed only once (Bicep deployment with Azure CLI[18]).

A JSON parameter file plus one inline override

az deployment group create --resource-group rg-app --template-file main.bicep --parameters '@prod.parameters.json' storageAccountType=Standard_GRS

The @ prefix also works for a single value: exampleArray=@arrayContent.json reads just that one parameter's value from a file that contains only the array, which is different from @prod.parameters.json, a whole parameter file. Inline array syntax depends on the shell: in Bash write exampleArray='["value1", "value2"]', and in cmd or PowerShell write exampleArray="['value1','value2']" (Bicep deployment with Azure CLI[18]).

Azure PowerShell

Azure PowerShell exposes each template parameter as a parameter of the deployment cmdlet, so -storagePrefix contoso or a native array such as -exampleArray $arrayParam works inline. A local parameter file goes in -TemplateParameterFile and a remote one in -TemplateParameterUri (Azure PowerShell deployment[19]). If a template parameter shares its name with a cmdlet parameter, such as ResourceGroupName, PowerShell presents the template's parameter with the postfix FromTemplate (parameter files[7]).

When you pass an external parameter file by URI with -TemplateParameterUri, you can't pass other values inline or from a local file, so the external file must hold every value (parameter files[7]).

Takeaway: the file named by --template-file is the definition, everything after --parameters is input, and the last value assigned to a parameter is the one deployed.

Passing a secret through a Key Vault reference

A JSON parameter file can point at a secret instead of containing it. Four parties take part: the template, which declares the input as a secure parameter; the parameter file, which names the vault and the secret; the key vault, which holds the value; and the user running the deployment, whose permission Resource Manager checks before it retrieves anything.

A parameter file entry that references a Key Vault secret

"adminPassword": {
  "reference": {
    "keyVault": {
      "id": "/subscriptions/<subscription-id>/resourceGroups/rg-security/providers/Microsoft.KeyVault/vaults/kv-deploy"
    },
    "secretName": "vmAdminPassword"
  }
}

The template declares adminPassword as securestring and doesn't say where the value comes from. During deployment, Resource Manager retrieves the secret named by secretName from the vault identified by keyVault.id, so the value never appears in the template or the parameter file (Key Vault parameter values[20]).

The two conditions

  1. The vault allows template deployment. Its enabledForTemplateDeployment setting must be true, for example with az keyvault update --name kv-deploy --enabled-for-template-deployment true (Key Vault parameter values[20]).
  2. The deployer holds the deploy action. The user who deploys the template needs Microsoft.KeyVault/vaults/deploy/action for the scope of the resource group and key vault. The Owner and Contributor roles include it, and a custom role containing only that action is the least-privilege choice (Key Vault parameter values[20]).

The second check is what stops someone from using a secret just by knowing the vault's resource ID: the ID only names the vault, and without the deploy action Resource Manager won't retrieve the secret for that user (Key Vault parameter values[20]). The deploy action is also separate from direct access to secret data. A user who only deploys a template that retrieves a secret needs no secret permissions in the vault's access policies, and you can grant deployment access without granting write access to the secrets (Key Vault parameter values[20]). The reverse doesn't work either: direct secret-read permission doesn't replace the vault's enabledForTemplateDeployment setting.

When the secret is passed as a parameter this way, the key vault can be in a different subscription from the resource group you're deploying to (Key Vault parameter values[20]). The Azure portal's template deployment interface doesn't support Key Vault references, so deploy such templates with Azure CLI or Azure PowerShell (portal deployment[21]). A Bicep parameters file retrieves the same kind of secret with the getSecret function instead of a reference entry (Bicep parameters files[22]).

Takeaway: a Key Vault reference needs both switches, the vault's template-deployment setting and the deployer's deploy/action permission; secret-read access is neither of them.

Deployment order: implicit and explicit dependencies

Resource Manager doesn't deploy resources in the order they appear in the file. It deploys resources that don't depend on each other in parallel and makes a resource wait only for the resources it depends on; you only define dependencies between resources deployed in the same template (ARM resource dependencies[3]). A dependency comes into existence in one of two ways:

A network interface that implicitly waits for its virtual network (Bicep)

resource vnet 'Microsoft.Network/virtualNetworks@2025-01-01' = {
  name: 'vnet-app'
  // ... location, address space and subnets
}

resource nic 'Microsoft.Network/networkInterfaces@2025-01-01' = {
  name: 'nic-vm1'
  location: location
  properties: {
    ipConfigurations: [
      {
        name: 'ipconfig1'
        properties: {
          subnet: {
            id: vnet.properties.subnets[0].id // symbol reference: implicit dependency
          }
        }
      }
    ]
  }
}

Because nic reads vnet.properties..., Resource Manager deploys the virtual network first. When an implicit dependency exists, don't add a dependsOn for the same pair (Bicep resource dependencies[23]). A virtual machine that refers to nic.id in its network profile waits for the network interface in turn, while a storage account that nothing refers to deploys in parallel with all three, as the figure below shows. Moving the nic block above the vnet block changes nothing, because Bicep elements can appear in any order (Bicep file structure[12]).

ARM boundaries that catch people

  • Passing a resource ID instead of a name to reference or list* creates no implicit dependency (ARM resource dependencies[3]).
  • resourceId() only builds an ID string; in ARM, by-name reference/list* calls and dependsOn create dependencies, as do calls to references(), a separate function rather than a misspelling of reference: it returns an array of the runtime states of a resource collection (the instances a loop creates; see Resource loops) and requires languageVersion 2.0 (ARM resource functions[8]). Putting [resourceId('Microsoft.Network/networkInterfaces', 'nic-vm1')] in a virtual machine's network profile identifies the network interface but doesn't make the virtual machine wait for it; add a dependsOn entry for the network interface.
  • The same resourceId() expression inside dependsOn does order the deployment, because dependsOn accepts resource names or resource IDs and the ordering comes from dependsOn itself (ARM template structure[6]).
  • A child resource nested inside its parent in an ARM template gets no automatic dependency on the parent; set dependsOn when the child must deploy after the parent (ARM resource dependencies[3]).

Keep explicit dependencies to what ordering needs

Every unnecessary dependsOn slows the deployment, because Resource Manager can't deploy those resources in parallel. It documents nothing either: after deployment a resource doesn't retain its deployment dependencies, so no command can show them (ARM resource dependencies[3]). Resource Manager detects circular dependencies during template validation (ARM resource dependencies[3]).

Takeaway: order comes from references and dependsOn, never from position in the file.

Virtual networkNetwork interfaceVirtual machineStorageaccountno dependency:deploys inparallelOrder comes from dependencies,not from position in the file
Deployment order for four resources: each arrow runs from a resource to the one that waits for it; the storage account has no dependency

Child resources in ARM templates and Bicep files

Some resources exist only inside another resource: a subnet belongs to a virtual network, and a virtual machine extension can't exist without its virtual machine (ARM child resources[24]). Whatever syntax you use, a child always resolves to a full type of the form {resource-provider-namespace}/{parent-resource-type}/{child-resource-type} and a full name of the form {parent-resource-name}/{child-resource-name} (Bicep child resources[25]). Both formats let you declare a child either inside its parent, where the position supplies the parent part, or outside it, where you supply the parent part yourself.

Declaration style ARM template Bicep file
Inside the parent In the parent's resources array, with type subnets and name Subnet1 Inside the parent's body: resource subnet 'subnets' = { name: 'Subnet1' }
Outside the parent At the top level, with type Microsoft.Network/virtualNetworks/subnets and name VNet1/Subnet1 At the top level, with the full type, parent: vnet and name: 'Subnet1'

The table follows ARM child resources[24] and Bicep child resources[25].

In an ARM template

A copy loop (the ARM copy element, which deploys several instances of one declaration; see Resource loops below) can't be used on a child resource nested in its parent, so to create several children you move the child to the top level (ARM resource iteration[26]). Once it is there, its position no longer implies the parent, so it needs the fully qualified type and a name that starts with the parent's name; a top-level child that keeps the short type subnets and the bare name Subnet1 no longer identifies its parent (ARM resource iteration[26]). As Deployment order explained, an ARM child doesn't automatically wait for its parent, which is why Microsoft's examples give the subnet a dependsOn on VNet1 in both styles (ARM child resources[24]). Child resources can be nested at most five levels deep (ARM child resources[24]).

In a Bicep file

The parent property supplies the parent part of the name. With parent: storage, where storage is the symbolic name of a storage account named examplestorage, the child's name is only its own name ('default' for a file service), while the full type is still written out (Bicep child resources[25]). Writing 'examplestorage/default' together with parent: storage would repeat the parent qualification. A child declared with parent depends on that parent implicitly (Bicep resource dependencies[23]), and declaring a child outside its parent is the documented way to create several children with a loop (Bicep child resources[25]).

Bicep also accepts the full name and type without parent, but that form isn't recommended and needs an explicit dependsOn, because the dependency can't be inferred. To reach a nested child from outside its parent, qualify it with the :: operator: with the table's declarations, vnet::subnet.properties.addressPrefix reads the address prefix of Subnet1, and both vnet and subnet are symbolic names, not Azure names (Bicep child resources[25]).

Subnets have one more wrinkle when a virtual network is redeployed; it is covered in Deployment modes: incremental and complete below.

Takeaway: nested declarations take the parent from their position; top-level ARM children spell out the full type and the parent/child name, and top-level Bicep children use parent with only their own name.

Resource loops

A loop creates several instances of one declaration from a count or a collection, so a single block can deploy three storage accounts, or one for each name in a list.

Three storage accounts from an ARM copy loop

{
  "type": "Microsoft.Storage/storageAccounts",
  "apiVersion": "2025-06-01",
  "name": "[format('{0}storage{1}', copyIndex(), uniqueString(resourceGroup().id))]",
  "location": "[parameters('location')]",
  "sku": { "name": "Standard_LRS" },
  "kind": "StorageV2",
  "copy": {
    "name": "storagecopy",
    "count": 3
  }
}

The same loop in Bicep

// location is the parameter declared in storage.bicep
resource storageAcct 'Microsoft.Storage/storageAccounts@2025-06-01' = [for i in range(0, 3): {
  name: '${i}storage${uniqueString(resourceGroup().id)}'
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
}]

In ARM, the copy element's count sets how many instances to create, and copyIndex() returns the current iteration, starting at 0; copyIndex(1) offsets it so names run 1, 2, 3 instead of 0, 1, 2 (ARM resource iteration[26]). In Bicep, the for expression iterates over range(startIndex, numberOfElements) or directly over an array, as in [for name in storageNames: {...}] (Bicep loops[27]).

Every instance needs a unique name, built from the index or the array element (Bicep loops[27]); a loop that gives every instance the same name identifies one resource, not several. The count can't be negative or exceed 800 iterations (ARM resource iteration[26], Bicep loops[27]), and the template as a whole is still limited to 800 resources (ARM template structure[6]).

Batches: how many at a time

By default the instances deploy in parallel and their order isn't guaranteed (ARM resource iteration[26]). To stagger an update, for example in production, deploy them in batches:

  • ARM: in the copy element, set "mode": "serial" and "batchSize": 2. Resource Manager then creates a dependency on earlier instances so that it doesn't start one batch until the previous batch completes, and batchSize can't exceed count (ARM resource iteration[26]).
  • Bicep: put @batchSize(2) above a resource or module loop; @batchSize(1) deploys strictly one at a time (Bicep loops[27]).

Batch size controls concurrency, while count (or the length of the collection) controls how many instances exist. Lowering count to slow a rollout changes the declared population instead: the dropped instances are no longer in the template, and in complete mode, which deletes resources the template omits, they become eligible for deletion (see Deployment modes: incremental and complete).

Takeaway: the count or collection decides how many instances exist, the name expression keeps them distinct, and the batch size decides how many deploy at once.

Conditional deployment

A condition decides whether a whole resource is deployed. In ARM, the condition element takes an expression that resolves to true or false; in Bicep, an if expression follows the = of a resource or module declaration (ARM conditional deployment[28], Bicep conditional deployment[29]).

A storage account deployed only when newOrExisting is new (ARM)

{
  "condition": "[equals(parameters('newOrExisting'), 'new')]",
  "type": "Microsoft.Storage/storageAccounts",
  "apiVersion": "2025-06-01",
  "name": "[parameters('storageAccountName')]",
  ...
}

The same condition in Bicep

resource saNew 'Microsoft.Storage/storageAccounts@2025-06-01' = if (newOrExisting == 'new') {
  name: storageAccountName
  ...
}

When newOrExisting is new, the storage account is deployed; otherwise this declaration is skipped (ARM conditional deployment[28]). The condition applies to the whole resource only (ARM conditional deployment[28]).

Three behaviors that follow from it

  1. No cascade to children. A parent's condition doesn't apply to its child resources. To make a parent and its children optional together, apply the same condition to each child resource type (ARM conditional deployment[28], Bicep conditional deployment[29]).
  2. Runtime functions still run. A reference or list* call that targets a conditional resource is evaluated even when the resource isn't deployed, and it can fail if the resource doesn't exist. Guard the call so it runs only when the resource is deployed: the if() function in ARM, for example [if(equals(parameters('newOrExisting'), 'new'), reference(parameters('storageAccountName')).primaryEndpoints.blob, '')], or the conditional operator ?: in Bicep (ARM conditional deployment[28], Bicep conditional deployment[29]).
  3. Dependencies adjust on their own. A resource can depend on a conditional resource like any other, and when the conditional resource isn't deployed, Resource Manager removes it from the required dependencies (ARM conditional deployment[28]). That is also why dependsOn can't fix behavior 2: it controls order, not whether an expression is evaluated.

A false condition has one more effect in complete mode, which deletes resources the template omits: there, a skipped resource can be deleted, as Deployment modes: incremental and complete explains.

Takeaway: a condition switches one whole declaration, never its children and never the lookups that point at it; guard those yourself.

Nested and linked templates and Bicep modules

Large deployments are usually split into smaller templates, and ARM templates and Bicep files use one mechanism for it: the parent deployment contains a resource of type Microsoft.Resources/deployments, and that resource runs a child deployment (linked and nested templates[30]). The table compares where each variant's child template comes from:

Variant Where the child's template comes from
Nested template (ARM) Inline, in the deployment resource's properties.template
Linked template (ARM) A separate file at properties.templateLink.uri
Module (Bicep) A module declaration pointing at a Bicep file or an ARM template, stored locally, in a registry or in a template spec

A template spec is an Azure resource that stores an ARM template, supports versions and is shared through Azure RBAC (template specs[31]); see Sharing templates with template specs below. Bicep converts modules into nested templates (Bicep modules[16]), and Resource Manager records each child deployment as its own entry in the deployment history (linked and nested templates[30]).

Nested and linked templates in ARM

A nested template that receives one input and returns one output

{
  "type": "Microsoft.Resources/deployments",
  "apiVersion": "2025-04-01",
  "name": "storageDeployment",
  "properties": {
    "mode": "Incremental",
    "expressionEvaluationOptions": { "scope": "inner" },
    "parameters": {
      "storagePrefix": { "value": "[parameters('storagePrefix')]" }
    },
    "template": {
      "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
      "contentVersion": "1.0.0.0",
      "parameters": { "storagePrefix": { "type": "string" } },
      "resources": [ ... ],
      "outputs": { "blobEndpoint": { "type": "string", "value": "..." } }
    }
  }
}

The parent reads the child's output with [reference('storageDeployment').outputs.blobEndpoint.value], naming the deployment resource and then the output (linked and nested templates[30]).

  • Inputs. Pass values inline through properties.parameters, as the listing does, or point to a parameter file with properties.parametersLink. Specifying both fails the deployment (linked and nested templates[30]).
  • Where a linked template can live. The templateLink.uri must be downloadable over HTTP or HTTPS by Resource Manager itself, so a file on your workstation or local network doesn't work. A private storage account with a SAS token works, but the URI, including the token, is logged in the deployment operations, and a storage account behind an Azure Storage firewall can't be used. Microsoft suggests a template spec instead of a SAS-secured link (linked and nested templates[30]).
  • Order between children. If one child deployment must finish before another, give the second a dependsOn on the first (linked and nested templates[30]). dependsOn only orders the deployments; values still travel only through parameters and outputs.

Expression evaluation scope (nested templates only)

The expressionEvaluationOptions.scope property decides where a nested template's expressions resolve, which covers parameters, variables, and functions such as resourceGroup() and subscription() (linked and nested templates[30]). This scope is not the deployment's target scope (the resource group, subscription, management group or tenant from Deploying across scopes); it only selects whether the parent template (outer) or the nested template (inner) resolves those expressions:

Scope Expressions resolve in Consequences
outer The parent template The default before languageVersion 2.0. The nested template can't use reference in its outputs for a resource it deploys, and secure values are stored as plain text in the deployment history.
inner The nested template The default under languageVersion 2.0, where outer is blocked. Anything the child needs from the parent must be passed through parameters, as in the listing.

To return a value from a resource the nested template creates, use inner scope or convert the nested template to a linked template (linked and nested templates[30]).

Bicep modules

Calling storage.bicep as a module

// ... location is a parameter of this calling file
module stgModule './storage.bicep' = {
  name: '${deployment().name}-storageDeploy'
  params: {
    location: location
  }
}

output storageBlobEndpoint string = stgModule.outputs.blobEndpoint

params supplies the module's parameters, and stgModule.outputs.blobEndpoint reads its blobEndpoint output through the module's symbolic name (Bicep modules[16]). Outputs expose the module's deployment results: the symbol stg inside storage.bicep isn't visible to the calling file, so expose any value you need as an output. Like resources, modules deploy in parallel unless they depend on other modules or resources (Bicep modules[16]).

The module's name becomes the name of the nested deployment resource and is optional; without it, a GUID is generated. If two deployments use the same module with the same static name against the same scope at the same time, one can show the other's output, so either leave name out or make it unique, as the listing does by using deployment().name as a prefix, provided each parent deployment has a unique name (Bicep modules[16]).

Takeaway: nested templates, linked templates and modules are all Microsoft.Resources/deployments resources; inputs go in through parameters, results come out through outputs, and dependsOn only sets the order.

Deploying across scopes

A file has one target scope, but a deployment can still place resources at other scopes through child deployments. That is how one subscription-level deployment can create a resource group and fill it in the same run.

Setting the file's scope

In Bicep, targetScope defaults to resourceGroup, so resource group deployments don't need to set it; the other values are subscription, managementGroup and tenant (Bicep file structure[12]). In an ARM template, the $schema file reflects the scope, as Reading an ARM template showed. Whatever the file declares, the deployment command must match it, as Running a deployment below describes.

Reaching another scope

A resource type can be deployed only at the scopes it supports. A subscription-level deployment can create resource groups and deploy subscription resources such as policy assignments, role assignments and budgets, and it reaches resource groups through nested deployments (subscription deployments[32]). A virtual machine or a storage account isn't on that list of subscription-level resources, so a subscription-scope file places it through a child deployment that targets a resource group.

  • Bicep: set the module's scope property; without it, the module deploys at the parent's target scope. Use the symbolic name of a resource group the file deploys, or a scope function such as resourceGroup('rg-app'), subscription(), managementGroup() or tenant() (Bicep modules[16]).
  • ARM: on the Microsoft.Resources/deployments resource in a subscription deployment, set resourceGroup to target a resource group; set subscriptionId and a location to target another subscription; set scope to / with a location to target the tenant (subscription deployments[32]).

The only prohibited transitions are from a resource group to a management group and from a subscription to a management group, and the user deploying the template must have access to every scope it targets (subscription deployments[32]).

Creating a resource group and deploying storage.bicep into it (main.bicep)

targetScope = 'subscription'

param location string

resource newRG 'Microsoft.Resources/resourceGroups@2025-04-01' = {
  name: 'rg-app'
  location: location
}

module stgModule './storage.bicep' = {
  name: 'storageDeploy'
  scope: newRG
  params: {
    location: location
  }
}

The module's scope refers to the newRG symbol, and a reference to another declaration's symbol creates an implicit dependency, so the resource group is deployed before the module and the storage account lands in rg-app (Bicep resource dependencies[23], Bicep modules[16]). The figure below traces that structure.

The ARM equivalent uses the subscription $schema and holds two resources: a Microsoft.Resources/resourceGroups resource and a Microsoft.Resources/deployments resource with "resourceGroup": "[parameters('rgName')]". The deployment resource needs a dependsOn on the resource group so the group exists before its contents deploy (subscription deployments[32]).

Takeaway: the file's scope decides the command, and child deployments (a Bicep module's scope, or ARM's resourceGroup, subscriptionId or scope properties) carry each resource to the scope it belongs in.

main.biceptargetScope = 'subscription'Subscription deploymentResource grouprg-app (created)Module stgModulescope: newRGStorage accountin rg-app
A subscription-scope Bicep file (main.bicep) that creates rg-app and deploys storage.bicep into it through a module scoped to that group

Running a deployment

Once a file is ready, deploying it is a single command whose family is fixed by the target scope. You can deploy from Azure CLI, Azure PowerShell, the Azure portal, the REST API or Azure Cloud Shell (What are ARM templates?[1]); Azure CLI and Azure PowerShell are the forms you type most often.

The command follows the scope

Deploying at resource group scope and at subscription scope (Azure CLI)

# Resource group scope: deployment data is stored in the resource group's location
az deployment group create --name storageDeploy --resource-group rg-app --template-file storage.bicep

# Subscription scope: --location says where the deployment's data is stored
az deployment sub create --name rgDeploy --location eastus --template-file main.bicep

The same two deployments in Azure PowerShell

New-AzResourceGroupDeployment -Name storageDeploy -ResourceGroupName rg-app -TemplateFile ./storage.bicep
New-AzSubscriptionDeployment -Name rgDeploy -Location eastus -TemplateFile ./main.bicep

Management group and tenant deployments use az deployment mg create and az deployment tenant create, or New-AzManagementGroupDeployment and New-AzTenantDeployment; New-AzSubscriptionDeployment is an alias of New-AzDeployment (Azure CLI deployment[4], Azure PowerShell deployment[19]). Depending on the scope of the deployment, you use a different command (Azure CLI deployment[4]), as the table Deployment command and settings by target scope, near the end of this topic, shows for all four scopes. To run a template, use these deployment commands rather than a resource-specific command such as New-AzVM, which builds one resource from its own arguments.

The deployment location

Subscription, management group and tenant deployments need a location for the deployment itself. That location is separate from the location of the resources you deploy and only specifies where the deployment data is stored; a resource group deployment stores it in the resource group's location (subscription deployments[32]). Azure CLI describes --location as "the location to store the deployment metadata" (az deployment sub[33]), so the deployment location is also called the metadata location.

For each deployment name, the location is immutable. If deployment1 was created in centralus, a later deployment named deployment1 with the location westus fails with the error code InvalidDeploymentLocation; either reuse the original location or choose a different deployment name (subscription deployments[32]). That holds even when the resources themselves now belong in another region, because the deployment location never placed them.

Local file, remote template or template spec

  • --template-file (-TemplateFile in PowerShell) deploys a local Bicep file or a .json or .jsonc ARM template (Azure CLI deployment[4]).
  • --template-uri (-TemplateUri) deploys an ARM template from an accessible URL. For linked templates with relative paths stored in a storage account, --query-string (-QueryString) supplies the SAS token (Azure CLI deployment[4], Azure PowerShell deployment[19]).
  • Azure CLI doesn't support deploying remote Bicep files: build the Bicep file into an ARM template with the Bicep CLI and host that JSON file instead (Bicep deployment with Azure CLI[18]).
  • --template-spec (-TemplateSpecId) deploys a stored template spec version, covered in Sharing templates with template specs below.

Deployment names and history

If you don't name a deployment, it takes the file's name: azuredeploy.json becomes azuredeploy, and main.bicep becomes main. Each run adds an entry with that name to the resource group's deployment history, and a later run with the same name replaces the earlier entry. If two deployments with the same name run concurrently against the same resource group, only the last one completes. Give each deployment a unique name, for example by appending a date, to keep separate history entries and avoid that conflict (Azure CLI deployment[4], Bicep deployment with Azure CLI[18]).

Deploying from the portal

In the portal, select Create a resource, search for template and choose Template deployment. From there you can build a template in the editor, start from a common template or load a quickstart template, edit it, and fill in its parameters (portal deployment[21]). The portal has limits the command line doesn't: its custom template blade can't use a parameter file (parameter files[7]), it doesn't support Key Vault references (portal deployment[21]), and it doesn't support complete mode (deployment modes[5]). Even a Marketplace deployment made through the portal runs an ARM template, which you can find in the deployment history (portal deployment[21]).

Takeaway: choose the command family from the scope, supply a deployment location for the wider scopes and keep it stable for each deployment name, and give deployments unique names.

Permissions a deployment needs

A template describes resources; it authorizes nothing. To deploy a Bicep file or ARM template, you need write access on the resources you're deploying and access to all operations on the Microsoft.Resources/deployments resource type. Deploying a virtual machine, for example, takes Microsoft.Compute/virtualMachines/write plus Microsoft.Resources/deployments/* (Azure CLI deployment[4]). The requirement applies at every scope you deploy to (Azure CLI deployment[4]), including each scope a child deployment targets (subscription deployments[32]).

  • What-if needs the same permissions. The what-if operation changes nothing, yet it has the same permission requirements as the deployment (Bicep what-if[34]). Assigning the Reader role because "what-if only reads" therefore doesn't let someone run a default what-if. Previewing changes with what-if below describes the one validation level that checks only read permissions on the resources.
  • Reading a template isn't deploying it. Read access to a template spec lets a user deploy its template without changing it, but the deployment still needs the permissions above at the destination (template specs[31]).
  • Secrets need their own action. A Key Vault reference additionally requires Microsoft.KeyVault/vaults/deploy/action, as Passing a secret through a Key Vault reference explains.

For a list of roles and the permissions they include, Microsoft's deployment guidance points to Azure built-in roles[35] (Azure CLI deployment[4]).

Takeaway: deploying needs write permission on the resources plus Microsoft.Resources/deployments/* at each target scope, and a default what-if needs the same.

Sharing templates with template specs

Sharing a template file usually means a public URL or SAS tokens, plus local copies that drift apart. A template spec avoids all three: it is an Azure resource of type Microsoft.Resources/templateSpecs that stores an ARM template, made of a main template and any linked templates, in a resource group. It supports versions and is shared through Azure RBAC (role-based access control) like any other Azure resource (template specs[31]).

Creating a version

Creating version 1.0a of a template spec from a local template

az ts create --name storageSpec --version "1.0a" --resource-group templateSpecRG --location "westus2" --template-file "./mainTemplate.json"

The Azure PowerShell equivalent is New-AzTemplateSpec. If the main template references linked templates, the command finds and packages them into the spec, and a template spec is limited to approximately 2 MB (template specs[31]).

Deploying a version

Instead of a path or URI, you deploy a template spec by its resource ID, and that ID names a specific version: /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Resources/templateSpecs/{template-spec-name}/versions/{template-spec-version} (template specs[31]).

Deploying version 1.0a into another resource group

id=$(az ts show --name storageSpec --resource-group templateSpecRG --version "1.0a" --query "id" --output tsv)
az deployment group create --resource-group demoRG --template-spec "$id"

In Azure PowerShell, pass the same ID to New-AzResourceGroupDeployment -TemplateSpecId. A template spec can be deployed to any scope, through the portal, Azure PowerShell or Azure CLI, or as a linked template inside a larger deployment (template specs[31]). A Bicep file can call one as a module with the path 'ts:<sub-id>/<rg-name>/<template-spec-name>:<version>' (Bicep modules[16]).

Who can do what

Two built-in roles exist: Template Spec Reader and Template Spec Contributor. Users need only read access to a template spec to deploy its template, so you can share it without letting others change it; they still need the deployment permissions from Permissions a deployment needs at the destination (template specs[31]). Access is managed through Azure RBAC rather than SAS tokens: a SAS token authorizes requests to a storage account and grants nothing on a template spec.

Takeaway: use a template spec when a team should deploy a governed, versioned template it can't edit, and deploy it by the version's resource ID.

Previewing changes with what-if

The what-if operation shows how resources would change if you deployed a file, without making any change to existing resources, and it works for resource group, subscription, management group and tenant deployments (Bicep what-if[34]).

Running it

Previewing a resource group deployment

az deployment group what-if --resource-group rg-app --template-file storage.bicep

The other scopes use az deployment sub what-if, az deployment mg what-if and az deployment tenant what-if. In Azure PowerShell, add the -WhatIf switch to the deployment cmdlet, for example New-AzResourceGroupDeployment -WhatIf. To preview and then decide, add --confirm-with-what-if (short form -c) to az deployment group create, or -Confirm to the PowerShell cmdlet; the command shows the predicted changes and asks whether to continue (Bicep what-if[34]).

Reading the result

What-if reports seven change types (Bicep what-if[34]):

Change type Meaning
Create The resource doesn't exist and will be created.
Delete The resource exists but isn't in the file; reported only for complete mode deployments.
Ignore The resource exists but isn't in the file, and won't be deployed or modified. Also reported when what-if reaches its expansion limits.
NoChange The resource will be redeployed and its properties won't change.
NoEffect The property is read-only and the service will ignore it.
Modify The resource will be redeployed and its properties will change.
Deploy The resource will be redeployed, but what-if can't tell whether properties change; seen only with the ResourceIdOnly result format.

The result format only controls detail: FullResourcePayloads, the default, lists property changes, and ResourceIdOnly lists only the resources. You set it with --result-format or -WhatIfResultFormat (Bicep what-if[34]); it doesn't change which checks run.

What what-if can't see

  • It can't resolve the reference function, so a property set from a reference expression is always reported as changing, even when the deployed value would stay the same (Bicep what-if[34]).
  • It shows these expressions unevaluated: nondeterministic functions such as newGuid() and utcNow(), references to secure parameter values, references to resources or resource properties not defined in the same template, and resource functions such as listKeys() (Bicep what-if[34]).
  • It doesn't expand templateLink, so resources deployed through linked templates, including template spec references, are missing from the results (Bicep what-if[34]).
  • It stops expanding nested templates at 500 nested templates, 800 resource groups or 5 minutes, and marks the remaining resources as Ignore (Bicep what-if[34]).
  • Properties that are set to default values during deployment can be reported as deleted although they won't change, which Microsoft calls noise (Bicep what-if[34]).

An Ignore result or an unresolved value is therefore a limit of the preview, not proof that a resource was checked and found unchanged.

Validation level

Azure CLI 2.76.0 or later adds --validation-level, and Azure PowerShell 13.4.0 or later adds -ValidationLevel, to set how thoroughly Resource Manager validates the file during what-if. The three values (Bicep what-if[34]):

Level What it checks
Provider (default) Full validation: syntax, resource definitions, dependencies, and permission checks that you can deploy every resource in the file.
ProviderNoRbac The same full validation of template and resources, but it checks only read permissions on each resource instead of full deployment permissions.
Template Static validation of syntax and structure only, skipping preflight checks (such as resource availability) and permission checks.

The permission rule in Permissions a deployment needs describes the default Provider level. ProviderNoRbac is the documented way to validate resource configurations for someone with read rather than deploy access to the resources. Switching the result format to ResourceIdOnly doesn't achieve that, because formatting doesn't change the permission check. A pass at the Template level means the file is well formed, not that the deployment would succeed (Bicep what-if[34]).

Takeaway: run what-if before a risky deployment, read Create, Modify and Delete carefully, and treat Ignore results, unresolved values and linked templates as blind spots.

Deployment modes: incremental and complete

The deployment mode answers one question: what happens to resources that already exist in the target resource group but aren't in the template? In both modes, Resource Manager tries to create every resource the template declares, takes no action on an existing resource whose settings are unchanged, and updates a resource whose property values changed. The default mode is incremental (deployment modes[5]).

Microsoft's example uses a resource group containing resources A, B and C and a template declaring A, B and D (deployment modes[5]). The figure below shows both outcomes:

  • Incremental: Resource Manager leaves C unchanged and adds D, so the group ends with A, B, C and D.
  • Complete: Resource Manager deletes C, so the group ends with A, B and D.

Incremental reapplies the whole resource

The resource definition in the template always describes the resource's final state and can't represent a partial update (deployment modes[5]). Incremental leaves resources the template doesn't declare unchanged; it doesn't mean individual properties are patched or that a declared parent's update can't remove child resources. When an existing resource is redeployed in incremental mode, all of its properties are reapplied: Resource Manager treats a property the template doesn't specify as an overwrite and resets it to its default value, so omitting a property that has a non-default value is a change. Specify every non-default value, not just the one you're changing (deployment modes[5]).

Two resources need extra care because some settings can be written on the resource or on one of its child resources (deployment modes[5]):

  • Subnets: define them in the subnets property of the Microsoft.Network/virtualNetworks resource, not as separate Microsoft.Network/virtualNetworks/subnets child resources. As long as the subnets are in the virtual network's definition, redeploying it doesn't lose them. The separate child-resource style from Child resources in ARM templates and Bicep files is valid, but redeploying a virtual network whose subnets property omits a subnet can remove it, as Microsoft's what-if example shows for subnet001 (what-if[34]).
  • Web app site configuration: these values live in the child resource type Microsoft.Web/sites/config. Redeploying the web app with an empty object for the site configuration values leaves that child resource unchanged, while providing new values updates it.

Complete mode deletes what the template omits

Complete mode deletes resources that exist in the resource group but aren't specified in the template. Its boundaries (deployment modes[5]):

  • Only resources in the resource group named in the deployment operation can be deleted; secondary resource groups the template also deploys to keep their resources.
  • Resource types differ. A parent resource missing from the template is deleted along with its children, but some child resources missing from the template aren't deleted while their parent remains: a DNS zone that stays in the template keeps its CNAME record even if the record isn't listed.
  • A locked resource group stops complete mode from deleting resources.
  • Only root-level templates support complete mode. Linked and nested templates must use incremental mode, subscription-level deployments don't support complete mode, and the portal doesn't offer it.

When the root template runs in complete mode and a linked or nested template targets the same resource group, its resources count as part of the template and aren't deleted (linked and nested templates[30]).

Complete mode compares the group against the template after loops and conditions are resolved:

  • Loops: any resource that isn't in the template after the copy loop is resolved is deleted (deployment modes[5]). Reducing a count from 5 to 3 keeps instances 0 to 2 and makes instances 3 and 4 eligible for deletion.
  • Conditions: a resource whose condition evaluates to false is deleted when the deployment uses REST API version 2019-05-10 or later, which the latest versions of Azure PowerShell and Azure CLI do; earlier versions keep it (deployment modes[5]).

Always run what-if before deploying in complete mode, so you see what it would delete (deployment modes[5]). Set the mode with --mode Complete in Azure CLI or -Mode Complete in Azure PowerShell (deployment modes[5]).

Deployment stacks for deletions

Incremental is the recommended mode. When a Bicep or ARM template deployment needs to delete resources, Microsoft recommends deployment stacks, because complete mode will be gradually deprecated (deployment modes[5]). A deployment stack is an Azure resource managing a group of resources as one unit; a resource removed from its template is deleted or detached (kept in Azure, unmanaged), per its actionOnUnmanage setting (deployment stacks[36]).

Takeaway: incremental preserves resources the template doesn't declare but reapplies each declared resource's properties, including child configuration; complete deletes omitted resources subject to the resource-type and lock boundaries above, and deployment stacks are the recommended path for intentional deletions.

Resource group hasA, B, CTemplate declaresA, B, DDeploy templateIncrementalCompleteResult: A, B, C, DC left unchangedResult: A, B, DC is deleted
Incremental versus complete mode for a group holding A, B, C and a template declaring A, B, D (Microsoft's deployment modes example)

Exporting templates and converting to Bicep

Two different operations are both called exporting a template, and they answer different questions (portal export[37]):

Aspect Export from resource group or resource Save from deployment history
What you get A new, autogenerated template: a snapshot of the resources' current state, including manual changes made after deployment An exact copy of the template that was deployed, ready to redeploy without changes
Which resources The resources you select All resources of that deployment; no subset, and no resources added at a different time
Properties and parameters All properties, including some you wouldn't normally set; most values hard-coded and parameters often missing Only the properties the deployment needed, with parameters for reuse
Format Bicep file or ARM template ARM template only

Export from the resource group or resource when you need changes made after the original deployment, want to choose the resources, or the resources weren't created with a template. Save from the history when you want an easy-to-reuse template and don't need later changes (portal export[37]). A setting changed in the portal last week can appear only in an export from the resource group or resource, never in a template saved from deployment history, because it was never part of the original template.

Review an export before reuse

Export isn't guaranteed to succeed and isn't a reliable way to turn existing resources into templates for production use (portal export[37]). Before reusing a template exported from a resource group or resource, work through these points from the same page:

  • Add parameters for the hard-coded, environment-specific values; the portal's Include parameters option is selected by default.
  • Check each apiVersion, because the export is generated from published schemas that occasionally lack the latest version for a resource type.
  • Add password parameters that the export left out.
  • Remove properties you wouldn't normally set during deployment.

Resource group export also stops at 200 resources: a larger group fails with the message Export template is not supported for resource groups more than 200 resources (portal export[37]). From the command line, az group export --name rg-app > main.json and Export-AzResourceGroup -ResourceGroupName rg-app -Path ./main.json export a resource group (decompile to Bicep[38]).

Converting between ARM templates and Bicep files

az bicep decompile --file main.json creates main.bicep in the same directory; add --force to overwrite an existing main.bicep. Without Azure CLI, the same Bicep CLI command is bicep decompile (decompile to Bicep[38]). There is no guaranteed mapping from an ARM template to Bicep, so review and fix the warnings and errors in the generated file; a conversion can also fail outright (decompile to Bicep[38]).

The opposite direction is az bicep build --file main.bicep, which writes main.json. You rarely run it yourself, because it runs automatically when you deploy a Bicep file (Bicep CLI commands[39]). Decompile and build produce functionally equivalent templates, but converting JSON to Bicep and back to JSON can return a template with different syntax; when deployed, it produces the same results (decompile to Bicep[38]). Byte-for-byte identity is therefore not the test of a good conversion.

Renamed parameters

Bicep identifiers, parameter names included, can contain only letters, digits and underscores, while ARM template parameter names can contain periods. The decompiler replaces each period with an underscore, so Security.Authentication.AAD.Tenant becomes Security_Authentication_AAD_Tenant (decompile to Bicep[38]). Update parameter files and every caller that passes those values to the new names: an entry that still uses the dotted name no longer matches a declared parameter, and an undeclared entry in a parameter file causes an error (see Supplying parameter values at deployment).

The figure below lays out both export paths and the conversion between the two formats.

Takeaway: export from the resource group or resource for today's state, save from the history for the original template, and treat exported and decompiled files as drafts to review before reuse.

Existing resourcesDeployment historyExport from groupor resource(current state)Save from history(exact template)az bicep decompileBicep fileaz bicep build convertsBicep to an ARM template
Two export paths for an ARM template (current state or exact original), decompiling either to a Bicep file, and building Bicep back to an ARM template

Deployment command and settings by target scope

SettingResource groupSubscriptionManagement groupTenant
Bicep targetScope valueresourceGroup (default, may be omitted)subscriptionmanagementGrouptenant
ARM $schema filedeploymentTemplate.jsonsubscriptionDeploymentTemplate.jsonmanagementGroupDeploymentTemplate.jsontenantDeploymentTemplate.json
Azure CLI deploy commandaz deployment group createaz deployment sub createaz deployment mg createaz deployment tenant create
Azure PowerShell cmdletNew-AzResourceGroupDeploymentNew-AzSubscriptionDeployment (alias of New-AzDeployment)New-AzManagementGroupDeploymentNew-AzTenantDeployment
Where deployment data is storedThe resource group's locationThe deployment location you supplyThe deployment location you supplyThe deployment location you supply
Azure CLI what-if commandaz deployment group what-ifaz deployment sub what-ifaz deployment mg what-ifaz deployment tenant what-if

Decision tree

Targets aresource group?Yesaz deploymentgroup createNoTargets asubscription?Yesaz deploymentsub create+ --locationNoTargets amanagement group?Yesaz deploymentmg create+ --locationNo (tenant)az deploymenttenant create+ --location

Sharp facts the exam loves — give these one last read before exam day.

Cheat sheet

Sharp facts the exam loves — scan these before test day.

Template schemas and resource API versions control different contracts

An ARM template's $schema identifies its template-language schema and deployment scope, while each resource's apiVersion selects the resource provider's REST API contract. Change the resource API version when a required property needs a newer API; contentVersion documents the template's own version rather than selecting Azure features.

Trap Changing contentVersion to enable a resource property that requires a newer resource-provider API.

2 questions test this
Parameters, variables, resources, and outputs serve different deployment roles

ARM parameters supply deployment-specific inputs, variables hold reusable values or expressions, resources describe the desired Azure resources, and outputs return results after deployment. Use parameters('name') to read an input and variables('name') to reuse a constructed value; place a resource endpoint needed by a later operation in outputs rather than treating it as a new resource.

Trap Treating a variable as a deployment input instead of declaring a parameter, even though variables can be constructed from parameter values.

2 questions test this
Resource declarations describe the desired resource but cannot relocate an existing one

An ARM resource declaration combines type, apiVersion, and name with resource-specific settings such as location, sku, and properties. A location parameter defaulting to resourceGroup().location uses the resource group's location because that expression was explicitly selected. Updating the location or type of an existing resource through redeployment fails, so create a replacement when those characteristics must change.

Trap Editing the location of an existing resource in a template as an in-place regional migration.

2 questions test this
Separately declared child resources need fully qualified types and parent-qualified names

An ARM child resource declared at the top level uses the full provider/parentType/childType and a name containing parentName/childName. Nesting the child inside its parent permits relative type and name forms instead. Move a nested child to a top-level declaration when it needs resource iteration, preserving the relationship through its qualified type and name.

Trap Moving a child resource to the template root while retaining only its relative type and unqualified child name.

2 questions test this
ARM language version 2.0 supports symbolic resource declarations and stronger type validation

An ARM template with languageVersion set to 2.0 can declare resources as an object keyed by symbolic names rather than only as an array. These symbols can be used in dependsOn and resource references, while definitions and aggregate constraints validate object properties and array elements. Changing a resource's apiVersion alone does not enable template-language features.

Trap Updating a storage account's apiVersion to enable template-language symbolic names.

2 questions test this
ARM expressions evaluate nested functions rather than treating them as naming text

ARM evaluates an expression enclosed in square brackets when deploying the template, evaluating nested function arguments before the enclosing function. For example, [concat('storage', uniqueString(resourceGroup().id))] combines a prefix with a deterministic suffix, and format('storage{0}', uniqueString(resourceGroup().id)) can construct the same kind of name; resourceGroup().id accesses a property of the returned object. The same uniqueString inputs produce the same suffix rather than a fresh random name. Strings supplied as values in a JSON parameter file are literal values, so placing that expression text there does not evaluate it as template code.

Trap Using a JSON parameter-file string to calculate a generated resource name, because parameter-file values are not evaluated as ARM expressions.

2 questions test this
Redeploying the same resource identity reconciles its desired state instead of creating another copy

ARM templates are declarative and idempotent: deploying unchanged desired configuration to the same environment does not intentionally create duplicate resources. A supported setting change updates the resource identified by its scope, type, and name, whereas a different resource name or target scope identifies a different resource to deploy. Keep resource identities stable when repeating a deployment to reconcile configuration rather than create another environment.

Trap Changing the resource name to label a configuration update, which targets a different Azure resource rather than the original one.

ARM nested deployment resources can target a different permitted deployment scope

An ARM JSON resource of type Microsoft.Resources/deployments can deploy its nested template at another permitted scope. From a subscription deployment, set resourceGroup to target a resource group, add subscriptionId when targeting another subscription, or use scope set to / for a tenant deployment. A nested subscription or tenant deployment also needs its own metadata location, and the deployer needs access to the destination scope. When the parent creates the target resource group, make the nested deployment depend on that group before deploying group-scoped resources.

Trap Placing a VM directly among a subscription template's subscription-scoped resources, because the VM must be deployed into a resource group through the appropriate nested deployment.

2 questions test this
ARM child deployments combine an explicit template source with scope-dependent value handoff

An ARM Microsoft.Resources/deployments resource embeds a nested template in properties.template or retrieves a linked template through properties.templateLink.uri, whose HTTP(S) location must be accessible to Resource Manager rather than only your workstation. Pass child inputs through properties.parameters, or parametersLink for a linked parameter file, and read returned values with reference('childDeployment').outputs.outputName.value. For an inline nested template, properties.expressionEvaluationOptions.scope selects whether parameters, variables, resourceGroup(), and subscription() resolve in the child context with inner or the parent context with outer; inner requires explicitly passing any parent inputs the child needs. Outer is the default before languageVersion 2.0, whereas 2.0 defaults to inner and blocks outer; use inner or a linked template when a child output must reference a resource created in that child.

Trap Using dependsOn to pass parent parameter values into a linked deployment, although dependencies order deployments rather than bind their inputs.

2 questions test this
Key Vault parameter references let deployment use a secret without storing it in the parameter file

An ARM parameter file can reference a Key Vault ID and secretName instead of containing the secret's literal value, with the template receiving a secure parameter. Enable enabledForTemplateDeployment on the vault and grant the deployer Microsoft.KeyVault/vaults/deploy/action at the required scope. This deployment authorization differs from direct secret data access and can work with a vault in another subscription; merely knowing its resource ID grants neither permission.

Trap Granting only direct secret-read permission while leaving enabledForTemplateDeployment disabled for an ARM parameter-file secret reference.

3 questions test this
Typed parameters make one deployment definition reusable across environments

ARM and Bicep parameters declare an input type and can provide a default used only when the caller supplies no value. Use an object for related configuration values or an array for a collection, rather than converting every field into a separate parameter. Both formats allow at most 256 parameters, so grouping related values can also address that limit.

Trap Hard-coding environment-specific settings into resource declarations instead of exposing caller-selectable inputs.

3 questions test this
Parameter constraints reject invalid input before resource deployment

ARM allowedValues and Bicep @allowed restrict accepted values; minValue and maxValue constrain integers, while minLength and maxLength constrain string length or array item count. Bicep uses the corresponding decorators above a parameter declaration. These limits are inclusive, and description metadata supplies guidance rather than enforcing permitted values.

Trap Using a parameter description to enforce a permitted SKU list, which only documents the expected input.

3 questions test this
Secure string and object parameters keep sensitive inputs out of deployment history

Use secureString or secureObject in ARM, or @secure() on a Bicep string or object parameter, for passwords and other sensitive inputs. Azure Resource Manager does not log these parameter values or save them in deployment history. Arrays and numbers cannot directly use the Bicep secure decorator, so wrap sensitive structured data in an object or serialize it as a string.

Trap Using an ordinary object parameter for credentials because its fields are grouped, which gives the object no secure-parameter treatment.

3 questions test this
Parameter defaults must be resolvable before deployment begins

ARM and Bicep resolve parameters before resource deployment, so defaults can use another parameter or a scope expression such as resourceGroup().location. They cannot obtain runtime resource state with reference or list functions, and cannot depend on a variable. Move runtime lookups into resource configuration or outputs where that state can be evaluated.

Trap Calling listKeys in a parameter default to obtain a key from a resource whose state is resolved at deployment runtime.

4 questions test this
Deployment parameter files provide a baseline that inline values can override

Azure CLI deployments accept inputs through --parameters, independently of --template-file. For a JSON parameters file use --parameters @prod.parameters.json and place later name=value assignments after it to override selected values; the last assignment wins. A .bicepparam file associates inputs with its deployment file through using, and supported CLI versions can deploy it with --parameters prod.bicepparam without a separate --template-file.

Trap Passing environment parameter values through --template-file, which selects the deployment definition rather than its inputs.

3 questions test this
A JSON parameter file must supply inputs that match the template's declared contract

A JSON deployment parameter file contains $schema, contentVersion, and a parameters object whose entries use value for supplied data or reference for a Key Vault secret. Entry names must match declared template parameters, and supplied values must have the declared types and satisfy their constraints. Every input without a template default needs a supplied value, while an input with a default may be omitted. Extra parameter entries that the template does not declare cause an error rather than becoming additional configuration.

Trap Adding a new parameter-file entry to set an undeclared resource property, because deployment accepts only inputs declared by the template.

3 questions test this
Deployment validation depth determines whether provider and deployment-permission checks run

For ARM or Bicep what-if operations in supported tools, choose Provider validation when you need resource-provider preflight checks and checks that the caller can deploy the resources; Provider is the default. ProviderNoRbac retains provider validation but checks resource read permissions instead of full deployment permissions, making it useful for reviewers who cannot deploy. Template performs static syntax and structure validation while skipping provider preflight and resource-permission checks, so success at that level does not establish deployment readiness. Azure CLI 2.76.0 or later exposes --validation-level, and Azure PowerShell 13.4.0 or later exposes -ValidationLevel.

Trap Changing the what-if result format to ResourceIdOnly to accommodate a read-only reviewer, although result formatting does not select a different permission-validation level.

3 questions test this
Deployment dependencies control ordering without file-order sequencing

Azure Resource Manager deploys unrelated resources in parallel and waits for declared or inferred prerequisites. In Bicep, referring to another deployed resource's symbolic name establishes an implicit dependency, including through parent relationships. Use dependsOn for an ordering requirement not otherwise expressed; unnecessary dependencies serialize work without creating a lasting operational relationship.

Trap Reordering resource declarations to make a network interface wait for its virtual network, which does not establish a dependency.

2 questions test this
ARM name-based runtime references can infer dependencies while resource IDs alone do not

In ARM, reference or list functions can infer a dependency on a resource deployed by that template when it is addressed by name. Supplying a resource ID to those functions does not create that implicit dependency, and constructing an ID with resourceId does not order deployment. ARM nesting also does not automatically make a child wait for its parent, so add dependsOn where required ordering is absent.

Trap Using resourceId for a NIC reference as the sole ordering mechanism, which constructs an identifier without waiting for NIC deployment.

2 questions test this
Resource loops generate independently named instances from a count or collection

ARM copy uses count and zero-based copyIndex() to produce resource instances, while Bicep uses for expressions over arrays or range(start, count). Give every generated resource a distinct name, and use an index offset when the naming sequence must start above zero. Loop counts cannot be negative or exceed 800 iterations; total deployment resource limits still apply.

Trap Using the same resource name in every loop iteration, which does not identify distinct resource instances.

2 questions test this
Batch controls stagger loop deployments instead of changing their total count

ARM resource loops run in parallel by default; set mode to serial and batchSize to control how many instances deploy before the next batch begins. Bicep expresses the same batching intent with @batchSize on a resource or module loop. Batch size controls concurrency, while count or collection length controls the total number of instances.

Trap Reducing a loop's count to limit concurrent updates, which reduces the declared population rather than batching it.

2 questions test this
Conditional resources require matching child conditions and guarded runtime lookups

ARM condition and Bicep resource or module if expressions decide whether an entire declaration is deployed. In ARM, a parent's condition does not cascade to children, and reference or list calls against an absent conditional resource can still be evaluated. Apply matching child conditions and guard runtime lookups with an if expression so optional resources do not leave invalid references.

Trap Adding dependsOn to suppress an optional resource's runtime lookup, which orders deployment but does not conditionally evaluate the lookup.

2 questions test this
A Bicep resource symbol is distinct from its deployed Azure name

A Bicep declaration such as resource vm 'Microsoft.Compute/virtualMachines@2025-04-01' uses vm as its local symbol, while its name property identifies the Azure resource. Use vm.id or other symbolic properties to connect declarations and outputs, and change name when the intended Azure identity should change. Parameters and variables are referenced directly by identifier rather than ARM parameters() or variables() syntax.

Trap Renaming the local Bicep symbol to change the VM's Azure name, which leaves the name property unchanged.

2 questions test this
Bicep existing declarations read resources without redeploying them

Use existing when a Bicep deployment needs an already-created resource's ID or properties without managing its definition again. Supply its name and, for another resource group or subscription, the appropriate scope object. A failed runtime property lookup can indicate an incorrect name or scope; existing is not a request to create a missing resource.

Trap Using a normal minimal resource declaration to reference an existing resource, which submits it for deployment rather than only reading it.

2 questions test this
Bicep parent properties preserve child identity without repeating the parent name

A Bicep child resource can be nested inside its parent or declared separately with parent set to the parent's symbol. In the separate form, provide the full child type but only the child's own name, because parent supplies the containing identity. This form lets a child participate in a top-level loop without embedding a resource loop in the parent declaration.

Trap Combining parent: storage with a child name that repeats storage's name, which duplicates the parent qualification.

2 questions test this
Bicep modules package reusable deployments behind explicit inputs and outputs

A Bicep module can reference another Bicep file or ARM JSON template, receive inputs through params, and return results through moduleSymbol.outputs.outputName. Modules compile into nested deployments rather than running imperative scripts. Give concurrent deployments unique deployment names, including unique explicit module names when used, so records and outputs do not interfere at the same scope.

Trap Reading an internal resource symbol directly from a separate module, which does not expose that symbol through its output contract.

2 questions test this
Bicep targetScope selects the main scope and modules can target other scopes

Bicep defaults targetScope to resourceGroup and also accepts subscription, managementGroup, or tenant. Set a module's scope to an appropriate scope object when its deployment belongs elsewhere. A subscription-level file can create a resource group and deploy group-scoped resources through a module targeting that group, provided the deployer has permissions at the affected scopes.

Trap Changing a VM's location to select another deployment scope, which changes geography rather than its administrative parent.

2 questions test this
Deployment commands must match the template's target scope

Use az deployment group create or New-AzResourceGroupDeployment for resource-group deployments. Subscription deployments use az deployment sub create or New-AzSubscriptionDeployment; management-group and tenant deployments use the corresponding mg or tenant CLI commands and New-AzManagementGroupDeployment or New-AzTenantDeployment. Non-resource-group deployments require a deployment location for metadata, separately from resource locations.

Trap Using New-AzVM to deploy an existing ARM template, which provisions a VM without being the template deployment command.

2 questions test this
Local deployment files and remote ARM templates use different command parameters

Azure CLI uses --template-file for local ARM or Bicep files and --template-uri for accessible remote ARM JSON templates. PowerShell uses -TemplateFile and -TemplateUri for those choices. Azure CLI does not directly deploy remote Bicep source URLs, so compile Bicep to ARM JSON for remote deployment or obtain the source locally.

Trap Supplying a remote .bicep URL to --template-uri, which expects a retrievable ARM template rather than Bicep source.

2 questions test this
Template deployment requires deployment operations and resource write permissions

A deployer needs the applicable resource write permissions and access to Microsoft.Resources/deployments operations at the deployment scope. Creating a VM therefore requires Microsoft.Compute/virtualMachines/write and deployment permissions; reading the template is not authorization to create its resources. What-if's default Provider validation level has the same deployment permission requirements even though it does not apply changes.

Trap Assigning Reader for what-if because it makes no changes, which does not supply the operation's deployment permissions.

2 questions test this
What-if previews changes without applying them and has runtime-resolution limits

Use az deployment group what-if or a deployment cmdlet's -WhatIf switch to inspect predicted creates, modifications, and deletions. What-if cannot fully resolve runtime reference expressions, so an unresolved comparison can report a change that actual deployment will not make. Treat Ignore results and unresolved values as preview limits rather than proof that every resource was checked and unchanged.

Trap Treating every predicted modification as guaranteed when its comparison contains an unresolved reference expression.

2 questions test this
Incremental deployment preserves omitted resources while complete mode can delete them

Incremental is the default recommended mode: resources omitted from the template remain in the resource group. Complete mode can delete omitted resources in the target group, subject to resource-type deletion behavior and locks; subscription deployments and nested or linked templates do not support complete mode. Microsoft recommends deployment stacks for managed deletions because complete mode is being deprecated.

Trap Using complete mode to update selected resources while retaining unrelated resources in the same target group.

2 questions test this
Incremental deployment does not mean partial property updates

When an existing resource appears in an incremental deployment, its definition describes the intended final state and properties are reapplied. Omitted nondefault settings can reset to defaults, so preserve every required setting instead of submitting only the changed field. Handle virtual-network subnet definitions and App Service site configuration carefully where settings also have child-resource representations.

Trap Using an incremental template as a one-property patch, which does not guarantee preservation of omitted resource settings.

2 questions test this
Complete mode evaluates the resolved resource population before deletion

In complete mode, reducing a copy loop can make earlier instances eligible for deletion because they are absent from the resolved template. A false condition also deletes an existing resource when the deployment API is 2019-05-10 or later, whereas older deployment APIs retain it. Preview the resolved changes before using this legacy pattern, and prefer deployment stacks for intentional deletion.

Trap Setting condition to false as a universal retain-but-skip switch, which does not preserve resources under current complete-mode semantics.

2 questions test this
Array and file parameter syntax follows the deployment tool and shell

For a Bash-based Azure CLI Bicep deployment, pass an inline numeric array as --parameters numbers='[1,2]' or use numbers=@numbers.json to read one value from a file. Azure PowerShell accepts a native array inline and uses -TemplateParameterFile for a local parameter file or -TemplateParameterUri for a remote one. Distinguish a whole parameter file from a file containing just one parameter's value.

Trap Passing a parameter-value JSON file as the deployment template, which does not provide a resource definition.

2 questions test this
An existing deployment name retains its original metadata location

For subscription and management-group deployments, an existing deployment name is bound to its metadata location at that deployment scope. Reusing that name with another location fails with InvalidDeploymentLocation, even when the resources themselves belong in the new region. Retain the original deployment location or choose a different deployment name.

Trap Changing the deployment location to follow a resource's new regional target, because an existing deployment name cannot change its metadata location.

Template Specs share versioned deployment templates through Azure RBAC

A Template Spec stores an ARM template and its packaged linked templates as an Azure resource, allowing administrators to share deployment definitions through Azure RBAC instead of distributing public URLs or SAS tokens. Deploy a selected version by supplying its resource ID, ending in Microsoft.Resources/templateSpecs/<name>/versions/<version>, to Azure CLI --template-spec or PowerShell -TemplateSpecId rather than supplying a local file or template URI. Read access to the spec, such as Template Spec Reader, lets the user retrieve that version without modifying it; deployment operations and permissions to create or update its resources are still required at the destination.

Trap Using a storage SAS token to grant access to a Template Spec resource, although SAS authorizes storage access rather than the spec's Azure RBAC operations.

2 questions test this
Resource export captures current state while history preserves the original template

Export a resource or resource group to capture current configuration, including manual changes since deployment. Save from deployment history for the exact ARM JSON used for that deployment instead. Resource export can select a subset, while history export includes the selected deployment's resources rather than arbitrary later additions.

Trap Exporting deployment history to capture later portal edits, which are not present in the original template.

2 questions test this
Generated exports need review before becoming reusable deployment definitions

Resource exports can contain hard-coded values, unnecessary properties, missing password parameters, or schemas omitting newer features. Review API versions and parameterize environment-specific values before reuse. Resource-group export is limited to groups with at most 200 resources and is not a guaranteed production-ready conversion of existing resources.

1 question tests this
Decompile converts ARM JSON to Bicep but does not guarantee a clean conversion

Use az bicep decompile --file main.json to create main.bicep, then review conversion warnings and errors before deployment. Building Bicep performs the opposite conversion to ARM JSON. A round trip can change syntax while preserving deployment behavior, so byte-for-byte identity is not the success criterion.

Trap Using Bicep build to convert ARM JSON into Bicep, which reverses the conversion direction.

2 questions test this
Decompilation can rename identifiers and require parameter-file updates

Bicep identifiers allow letters, digits, and underscores rather than periods in parameter names. Decompiling ARM dotted parameter names replaces periods with underscores. Update parameter files and external callers to the resulting names, rather than assuming their original input keys remain compatible.

Trap Keeping dotted ARM input names after Bicep conversion has replaced them with underscored identifiers.

2 questions test this

References

  1. https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/overview
  2. https://learn.microsoft.com/en-us/credentials/certifications/resources/study-guides/az-104
  3. https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/resource-dependency
  4. https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/deploy-cli
  5. https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/deployment-modes
  6. https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/syntax
  7. https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/parameter-files
  8. https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/template-functions-resource
  9. https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/parameters
  10. https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/template-expressions
  11. https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/template-functions-string
  12. https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/file
  13. https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/resource-declaration
  14. https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/existing-resource
  15. https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/deploy-to-resource-group
  16. https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/modules
  17. https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/parameters
  18. https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/deploy-cli
  19. https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/deploy-powershell
  20. https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/key-vault-parameter
  21. https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/deploy-portal
  22. https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/parameter-files
  23. https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/resource-dependencies
  24. https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/child-resource-name-type
  25. https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/child-resource-name-type
  26. https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/copy-resources
  27. https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/loops
  28. https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/conditional-resource-deployment
  29. https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/conditional-resource-deployment
  30. https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/linked-templates
  31. https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/template-specs
  32. https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/deploy-to-subscription
  33. https://learn.microsoft.com/en-us/cli/azure/deployment/sub
  34. https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/deploy-what-if
  35. https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles
  36. https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/deployment-stacks
  37. https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/export-template-portal
  38. https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/decompile
  39. https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/bicep-cli