azure-iac-bicep

name

azure-iac-bicep

description

Author, refactor, validate, and deploy Azure infrastructure as code in Bicep (preferred) and ARM JSON. Use when creating or editing .bicep / .bicepparam files, designing modules, decompiling or migrating ARM templates to Bicep, wiring what-if and deployment-stack workflows, hardening IaC for security (managed identity, private endpoints, no secrets in templates), or generating GitHub Actions pipelines that deploy Bicep. Triggers on "write a Bicep module", "convert this ARM template", "deploy this to a resource group", "what-if", "bicepparam", "az deployment", or any Azure infrastructure-as-code authoring request.

Azure IaC: Bicep + ARM

Production-grade Azure infrastructure as code. Bicep is the default authoring language; ARM JSON is the compile target and the fallback for tooling that has not adopted Bicep. Decompile legacy ARM to Bicep, never hand-author new ARM JSON.

When to load reference files

This file is the index. Load the deeper material only when the task needs it:

You are...	Read
Authoring a module, picking a scope, choosing decorators, wiring outputs	references/module-patterns.md
Migrating ARM JSON to Bicep, or deciding Bicep vs ARM vs Terraform	references/arm-vs-bicep.md
Running lint / what-if / deploy / deployment stacks, or building a CI pipeline	references/deploy-runbook.md

Documentation-first mandate

Resource API shapes drift. Before emitting any resource declaration, confirm the type, apiVersion, and required properties against the live schema rather than memory:

• Call the mcp__azure__bicepschema tool for the exact resource type (for example Microsoft.Storage/storageAccounts) to get current apiVersion and property names.
• For Terraform-adjacent questions, call mcp__azure__azureterraformbestpractices.
• For broader service guidance, call mcp__azure__get_azure_bestpractices and mcp__ms-learn__microsoft_docs_search.

If those tools are unavailable, state plainly that you are reasoning from training knowledge and flag that the user must validate the apiVersion against the current provider schema. Never invent an apiVersion or a property name. A template that fails at deploy time on a bad property is a sprint blocker.

Non-negotiable authoring rules

1. No secrets in templates or parameter files. Reference Key Vault with the getSecret() function from a .bicepparam file or a Microsoft.KeyVault/vaults existing reference. Never a literal password, key, or connection string. Mark sensitive parameters @secure().
2. Identity over keys. Default to system-assigned managed identity and RBAC role assignments. Reach for shared keys or SAS only when a service genuinely lacks managed-identity support, and say so.
3. Parameterize environment, not structure. Parameters carry what changes per environment (name prefixes, SKUs, region, scale). The resource graph stays declarative and identical across environments.
4. Idempotent by construction. Bicep deployments are incremental and re-runnable. Use deterministic names (uniqueString(resourceGroup().id) patterns) so re-runs converge rather than duplicate.
5. Every parameter is decorated. @description() on every parameter and output. @allowed(), @minLength(), @maxLength(), @minValue(), @maxValue() wherever a constraint exists.
6. Comments justify design, not syntax. Explain why a SKU, a scope, or a dependency exists. The Bicep already shows what.
7. Modules for reuse, not for everything. Extract a module when a unit is reused or independently testable. Do not shred a single-purpose template into ceremony.

Minimal module shape

// Storage account hardened for an internal data-landing zone.
// TLS1_2 floor and disabled public blob access are compliance requirements, not defaults.
targetScope = 'resourceGroup'

@description('Short environment moniker used in resource naming, e.g. prod, stg, dev.')
@allowed(['dev', 'stg', 'prod'])
param environment string

@description('Azure region for all resources. Defaults to the resource group location.')
param location string = resourceGroup().location

@description('SKU for the storage account. Standard_ZRS for prod resilience.')
@allowed(['Standard_LRS', 'Standard_ZRS', 'Standard_GRS'])
param storageSku string = 'Standard_ZRS'

// Deterministic, globally-unique, lowercase name within the 24-char limit.
var storageName = toLower('st${environment}${uniqueString(resourceGroup().id)}')

resource storage 'Microsoft.Storage/storageAccounts@2024-01-01' = {
  name: storageName
  location: location
  sku: {
    name: storageSku
  }
  kind: 'StorageV2'
  properties: {
    minimumTlsVersion: 'TLS1_2'
    allowBlobPublicAccess: false
    supportsHttpsTrafficOnly: true
    networkAcls: {
      defaultAction: 'Deny'
    }
  }
}

@description('Resource ID of the storage account for downstream role assignments.')
output storageId string = storage.id

@description('Primary blob endpoint for application configuration.')
output blobEndpoint string = storage.properties.primaryEndpoints.blob

The apiVersion (2024-01-01) above is illustrative. Confirm the current one via mcp__azure__bicepschema before shipping.

The deploy loop (always in this order)

# 1. Compile + lint. Fails fast on bad property names and missing required fields.
az bicep build --file main.bicep

# 2. Preview. Shows create/modify/delete BEFORE anything changes.
az deployment group what-if \
  --resource-group rg-warnerco-prod \
  --template-file main.bicep \
  --parameters main.bicepparam

# 3. Deploy incrementally (the default mode; never use Complete unless you mean it).
az deployment group create \
  --resource-group rg-warnerco-prod \
  --template-file main.bicep \
  --parameters main.bicepparam

Full lifecycle, deployment stacks, and the GitHub Actions pipeline are in references/deploy-runbook.md.

Parameter files: use .bicepparam, not JSON

// main.bicepparam — typed, supports expressions and Key Vault references.
using './main.bicep'

param environment = 'prod'
param storageSku = 'Standard_ZRS'
// Pull a secret at deploy time; the value never lands in source control.
param adminPassword = getSecret('00000000-0000-0000-0000-000000000000', 'rg-secrets', 'kv-warnerco', 'sql-admin-password')

Relationship to the azure-architect agent

This skill is the authoring and deployment layer. The azure-architect agent owns service selection and Well-Architected trade-offs. When a request is "which service and why", that is architecture: defer to the agent's WAF assessment first, then return here to express the chosen design as Bicep. The agent is configured to invoke this skill whenever a decision lands in concrete IaC.