Microsoft Azure — ARM Templates & Bicep

Azure is Microsoft's cloud computing platform offering over 200 services. This article covers arm templates & bicep with production-ready configurations, best practices, and hands-on examples.

Why ARM Templates and Bicep Exist

Azure Resource Manager (ARM) templates are the native infrastructure-as-code (IaC) format for Azure. They define resources declaratively in JSON. Bicep is a domain-specific language (DSL) that transpiles to ARM templates, offering cleaner syntax, modularity, and type safety. Both are idempotent: deploying the same template multiple times yields the same state. ARM templates are verbose and error-prone due to JSON's lack of expressions and modularity. Bicep solves this with simpler syntax, file modularity, and built-in linting. In production, you should prefer Bicep for new projects but understand ARM templates for legacy systems and debugging. The Azure platform itself uses ARM under the hood for all resource manager operations.

param location string = resourceGroup().location
param storageName string = uniqueString(resourceGroup().id)

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

Authoring Your First Bicep File

Start with a simple resource group and storage account. Bicep uses declarative syntax: you define what you want, not how to create it. Parameters allow customization without changing the template. The uniqueString function generates a deterministic hash based on inputs. Always use parameters for values that change between environments (dev, test, prod). Avoid hardcoding names, locations, or SKUs. Use resourceGroup().location as default to align with the resource group's region. Bicep supports all ARM template functions plus additional ones like resourceGroup(), subscription(), and uniqueString(). The output block returns values after deployment, useful for passing to other templates or scripts.

param location string = resourceGroup().location
param storageName string = 'stg${uniqueString(resourceGroup().id)}'
param sku string = 'Standard_LRS'

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

output storageEndpoint string = stg.properties.primaryEndpoints.blob

Parameters, Variables, and Outputs

Parameters are inputs to your template. Use decorators like @minLength, @maxLength, @allowed, and @secure for validation and security. Variables are computed values that simplify expressions. Outputs return values after deployment. In production, use parameters for environment-specific settings (e.g., VM size, number of instances) and variables for derived values (e.g., full resource names). Avoid using parameters for secrets; use @secure('password') for secure strings or reference Key Vault. Bicep supports complex types like arrays and objects. Use object parameters for grouping related settings. Always provide sensible defaults for parameters to enable quick deployments.

@minLength(3)
@maxLength(24)
@description('Storage account name')
param storageName string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Premium_LRS'
])
param sku string = 'Standard_LRS'

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

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

output storageEndpoint string = stg.properties.primaryEndpoints.blob

Resource Dependencies and Referencing

Bicep automatically detects dependencies when you reference a resource's symbolic name. For example, if a virtual machine references a network interface, Bicep knows the NIC must exist first. You can also use dependsOn explicitly, but it's rarely needed. Implicit dependencies are safer and more maintainable. For cross-resource references, use the properties of the resource. For example, nic.properties.ipConfigurations[0].properties.subnet.id. Avoid hardcoding resource IDs; use the resourceId() function or symbolic reference. In production, incorrect dependency ordering is a common cause of deployment failures. Let Bicep handle it.

param location string = resourceGroup().location

resource vnet 'Microsoft.Network/virtualNetworks@2023-01-01' = {
  name: 'vnet-${uniqueString(resourceGroup().id)}'
  location: location
  properties: {
    addressSpace: {
      addressPrefixes: [
        '10.0.0.0/16'
      ]
    }
  }
}

resource subnet 'Microsoft.Network/virtualNetworks/subnets@2023-01-01' = {
  parent: vnet
  name: 'subnet-1'
  properties: {
    addressPrefix: '10.0.1.0/24'
  }
}

resource nic 'Microsoft.Network/networkInterfaces@2023-01-01' = {
  name: 'nic-${uniqueString(resourceGroup().id)}'
  location: location
  properties: {
    ipConfigurations: [
      {
        name: 'ipconfig1'
        properties: {
          subnet: {
            id: subnet.id
          }
        }
      }
    ]
  }
}

Modules: Reusing and Composing Templates

Modules are Bicep files that can be referenced from other Bicep files. They enable reuse and composition. A module can be a simple resource group or a complex application stack. Modules have their own parameters and outputs. Use module keyword to reference a module file. Modules can be local files or published to a registry. In production, use modules to standardize common patterns (e.g., a standard storage account module with security defaults). Modules also enforce naming conventions and tagging policies. Always version your modules and use semantic versioning. Avoid modules that are too large or too small; aim for a single responsibility.

param location string = resourceGroup().location

module storageModule './modules/storage.bicep' = {
  name: 'storageDeployment'
  params: {
    location: location
    sku: 'Standard_GRS'
  }
}

output storageEndpoint string = storageModule.outputs.storageEndpoint

Deploying with Azure CLI and PowerShell

Deploy Bicep files using az deployment group create for resource groups or az deployment sub create for subscriptions. Use --parameters to pass parameter values. For CI/CD, use --parameters @params.json to load a parameter file. PowerShell uses New-AzResourceGroupDeployment. Always use --what-if to preview changes before deployment. In production, integrate deployment into pipelines (Azure DevOps, GitHub Actions). Use deployment stacks for managing resource lifecycles. Avoid deploying directly from a developer's machine; use service principals with least privilege. Monitor deployment logs for errors and use --verbose for debugging.

#!/bin/bash
resourceGroupName='myResourceGroup'
location='eastus'

# Create resource group
az group create --name $resourceGroupName --location $location

# Preview deployment
az deployment group what-if \
  --resource-group $resourceGroupName \
  --template-file main.bicep \
  --parameters storageName=mystorage

# Deploy
az deployment group create \
  --resource-group $resourceGroupName \
  --template-file main.bicep \
  --parameters storageName=mystorage

Handling Secrets and Key Vault Integration

Never hardcode secrets in templates. Use Azure Key Vault to store secrets and reference them in Bicep. Use the getSecret function to retrieve a secret from Key Vault. The Key Vault must be in the same subscription and the deploying identity must have read access. For secure parameters, use @secure('password') decorator. In production, use managed identities for the deployment service principal to access Key Vault. Avoid passing secrets as outputs; they can be logged. Use @secure() on outputs if necessary. For database connection strings, construct them in the template using secrets.

param keyVaultName string
param secretName string

resource kv 'Microsoft.KeyVault/vaults@2023-01-01' existing = {
  name: keyVaultName
}

resource sqlServer 'Microsoft.Sql/servers@2023-01-01' = {
  name: 'sql-${uniqueString(resourceGroup().id)}'
  location: resourceGroup().location
  properties: {
    administratorLogin: 'adminuser'
    administratorLoginPassword: kv.getSecret(secretName)
  }
}

Advanced: Conditions, Loops, and Nested Deployments

Bicep supports conditions (if), loops (for), and nested deployments via modules. Use conditions to deploy resources only in certain environments (e.g., skip a diagnostic setting in dev). Use loops to create multiple instances of a resource (e.g., multiple VMs). For complex orchestration, use nested deployments with module and deploymentScript for custom scripts. In production, avoid deep nesting; prefer modules. Loops can be resource-level or property-level. Use batchSize for parallel deployment. Conditions can also be used on properties. Always test loops with small counts first to avoid hitting API limits.

param environment string = 'dev'
param vmCount int = 2

resource vnet 'Microsoft.Network/virtualNetworks@2023-01-01' = {
  name: 'vnet-${uniqueString(resourceGroup().id)}'
  location: resourceGroup().location
  properties: {
    addressSpace: {
      addressPrefixes: [
        '10.0.0.0/16'
      ]
    }
  }
}

resource nic 'Microsoft.Network/networkInterfaces@2023-01-01' = [for i in range(0, vmCount): {
  name: 'nic-${i}-${uniqueString(resourceGroup().id)}'
  location: resourceGroup().location
  properties: {
    ipConfigurations: [
      {
        name: 'ipconfig1'
        properties: {
          subnet: {
            id: (i == 0 ? vnet.properties.subnets[0].id : vnet.properties.subnets[1].id)
          }
        }
      }
    ]
  }
}]

resource vm 'Microsoft.Compute/virtualMachines@2023-01-01' = [for i in range(0, vmCount): if (environment != 'dev' || i == 0) {
  name: 'vm-${i}-${uniqueString(resourceGroup().id)}'
  location: resourceGroup().location
  properties: {
    hardwareProfile: {
      vmSize: 'Standard_DS2_v2'
    }
    networkProfile: {
      networkInterfaces: [
        {
          id: nic[i].id
        }
      ]
    }
  }
}]

Testing and Validation

Test Bicep templates with bicep build to check syntax and bicep decompile to round-trip. Use az deployment group validate to validate against Azure Resource Manager. For unit testing, use Pester (PowerShell) or custom scripts to verify outputs. In production, integrate validation into CI/CD: run bicep build and what-if in pull requests. Use Azure Policy to enforce compliance (e.g., require tags). Test in a sandbox subscription before production. Use deployment stacks to manage resource groups as a unit. Always test parameter combinations that could break the template.

#!/bin/bash
# Validate syntax
bicep build main.bicep

# Validate deployment
az deployment group validate \
  --resource-group test-rg \
  --template-file main.bicep \
  --parameters @params.test.json

# What-if
az deployment group what-if \
  --resource-group test-rg \
  --template-file main.bicep \
  --parameters @params.test.json

Production Patterns: Deployment Stacks and Policy

Deployment stacks (preview) allow you to manage a collection of resources as a single unit. They support deny-settings to prevent manual changes. Combine with Azure Policy to enforce tagging, allowed locations, and SKUs. Use deploymentScripts for custom provisioning steps (e.g., running a script after resource creation). In production, use policy to enforce that all resources are deployed via Bicep (deny manual creation). Use deployment stacks to detect drift. Always use what-if before updating a stack. Avoid using deployment stacks for critical resources without testing.

param location string = resourceGroup().location

resource stg 'Microsoft.Storage/storageAccounts@2023-01-01' = {
  name: 'stg${uniqueString(resourceGroup().id)}'
  location: location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

resource policyAssignment 'Microsoft.Authorization/policyAssignments@2023-01-01' = {
  name: 'enforce-bicep-only'
  properties: {
    policyDefinitionId: '/providers/Microsoft.Authorization/policyDefinitions/...'
    parameters: {}
  }
}

Debugging and Troubleshooting

Common issues: syntax errors, missing API versions, incorrect resource IDs, and permission errors. Use bicep build to catch syntax errors. Use az deployment group validate for semantic errors. Check deployment logs with az deployment group show -n <deployment-name> -g <rg> --query properties.error. For runtime errors, enable debug logging with --debug. Use --verbose for detailed output. In production, set up alerts for deployment failures. Use what-if to understand changes. If a deployment fails, roll back by redeploying the previous version. Never manually fix resources; always fix the template and redeploy.

#!/bin/bash
# Deploy with verbose output
az deployment group create \
  --resource-group my-rg \
  --template-file main.bicep \
  --parameters @params.json \
  --verbose 2>&1 | tee deploy.log

# Check error details
az deployment group show \
  --resource-group my-rg \
  --name myDeployment \
  --query properties.error

# What-if for troubleshooting
az deployment group what-if \
  --resource-group my-rg \
  --template-file main.bicep \
  --parameters @params.json

Migrating from ARM to Bicep

Use bicep decompile to convert ARM templates to Bicep. Review the output; decompilation may not be perfect. Manually refactor to use modules and remove hardcoded values. Use bicep build to verify the round-trip. In production, migrate incrementally: start with simple resources, then move to complex ones. Use --force to overwrite existing Bicep files. After migration, test with what-if and deploy to a non-production environment. Keep the ARM template as a backup until the Bicep version is proven. Document any manual changes made during migration.

#!/bin/bash
# Decompile ARM template to Bicep
bicep decompile template.json --force

# Build Bicep to verify
bicep build template.bicep

# Compare with original
az deployment group what-if \
  --resource-group test-rg \
  --template-file template.bicep \
  --parameters @params.json

Bicep Module Registry: Publishing and Consuming Modules at Scale

Bicep modules enable reuse across teams. Publish modules to a private Azure Container Registry (ACR) using bicep publish or az bicep publish. The target path follows the format br:.azurecr.io/:. Use semantic versioning (e.g., v1.0.0) and never use :latest in production — tags are mutable and can cause unexpected changes. Enable --with-source to embed the original Bicep source alongside the compiled ARM JSON, allowing consumers to press F12 in VS Code to see the module code. Configure moduleAliases in bicepconfig.json to avoid typing the full registry FQDN in every file. For access control, grant AcrPush to publishers and AcrPull to consumers via ACR RBAC. Publish modules with @description on all parameters and outputs, @secure() on secrets, and @minLength/@maxLength/@allowed decorators for validation. In CI/CD, automate publishing on merge to main: lint, test, derive the next semantic version, publish, and generate a changelog. Consumer teams pin exact versions, upgrade at their own pace, and use what-if to validate before applying updates. For public modules, use the Azure Verified Modules (AVM) registry which provides Microsoft-tested, production-ready modules.

#!/bin/bash
# Publish a Bicep module to a private ACR registry
az bicep publish \
  --file modules/storage-account/main.bicep \
  --target "br:myregistry.azurecr.io/bicep/modules/storage-account:1.0.0" \
  --documentation-uri "https://github.com/myorg/bicep-modules/tree/main/modules/storage-account" \
  --with-source

# bicepconfig.json for alias
cat bicepconfig.json
{
  "moduleAliases": {
    "br": {
      "platform": {
        "registry": "myregistry.azurecr.io",
        "modulePath": "bicep/modules"
      }
    }
  }
}

# Consume with alias
# module stg 'br/platform:storage-account:1.0.0' = { ... }

Target Scopes: Deploying to Subscriptions, Management Groups, and Tenants

Bicep supports four deployment scopes: resourceGroup (default), subscription, managementGroup, and tenant. Set targetScope = 'subscription' to deploy subscription-level resources like resource groups, policy definitions, role assignments, and budgets. Use targetScope = 'managementGroup' for management group-level policies and RBAC. Use targetScope = 'tenant' for management groups themselves and tenant-level policy initiatives. When targeting a broader scope, use linked modules to deploy child resources. For example, a subscription-scoped Bicep can create a resource group and then use a module with scope: resourceGroup to deploy resources within it. Use the scope property on modules to change context: scope: resourceGroup('rg-name'), scope: subscription(), scope: managementGroup('mg-id'), or scope: tenant(). Deploy with the matching CLI command: az deployment sub create for subscription, az deployment mg create for management group, az deployment tenant create for tenant. Always use what-if at every scope level to preview changes. For management group and tenant deployments, the deploying identity needs elevated permissions (e.g., User Access Administrator or Global Administrator).

targetScope = 'subscription'

param rgName string = 'rg-prod'
param location string = 'eastus'

// Create resource group at subscription scope
resource rg 'Microsoft.Resources/resourceGroups@2023-01-01' = {
  name: rgName
  location: location
}

// Deploy a storage account inside the resource group using a module
module stg 'br/platform:storage-account:1.0.0' = {
  name: 'storageDeployment'
  scope: resourceGroup(rgName)
  params: {
    location: location
    sku: 'Standard_GRS'
  }
}

// Assign a role at subscription scope
resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(subscription().id, 'Contributor')
  properties: {
    principalId: '00000000-0000-0000-0000-000000000000'
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b24988ac-6180-42a0-ab88-20f7382dd24c')
  }
}