Azure Bicep Skill

Azure Bicep Skill

Microsoft's proven-practice guidance for production Bicep deployments, distilled. Use this skill whenever Bicep code is being authored, reviewed, or refactored, or when picking between custom modules and Azure Verified Modules.

When to use

Trigger this skill when you see any of the following:

• A .bicep or .bicepparam file being created, edited, or reviewed
• A request involving "landing zone," "AVM," "Azure Verified Module," "what-if," or "bicepconfig"
• A question about Bicep scopes (targetScope), parameter typing, or output design
• A GitHub Actions workflow that deploys Bicep
• A choice between Bicep and Terraform (Bicep is the default for Tim's stack; only deviate with explicit justification)
• A custom module being proposed when an AVM module exists for the same resource

Do not trigger for: pure ARM JSON work (recommend converting to Bicep first), Terraform-only workflows, Azure portal click-ops walkthroughs.

Core principles

1. AVM first, custom second

Azure Verified Modules are Microsoft-published, WAF-aligned, versioned Bicep modules in the public Bicep Registry. They have built-in support for diagnostics, managed identities, private endpoints, RBAC assignments, and tagging. Prefer them over hand-rolled modules.

Why: AVM modules are maintained by the product groups, tested across regions, and updated for breaking API changes. Reinventing them is technical debt you will pay forever.

// Preferred: AVM resource module, version-pinned
module storage 'br/public:avm/res/storage/storage-account:0.14.3' = {
  name: 'storage-deployment'
  params: {
    name: storageAccountName
    location: location
    skuName: 'Standard_GRS'
    tags: tags
  }
}

See references/AVM-GUIDE.md for the module catalog, the resource (res) vs pattern (ptn) distinction, and version-pinning strategy.

2. Strong types and decorators on every param

Bicep parameters should be self-documenting and self-validating.

@description('Cost center for chargeback. Must match Finance master list.')
@minLength(4)
@maxLength(8)
param costCenter string

@description('Environment tier. Drives SKU selection and retention policies.')
@allowed([
  'dev'
  'test'
  'prod'
])
param environment string

@description('Admin password. Sourced from Key Vault via getSecret().')
@secure()
param sqlAdminPassword string

Why: Decorators turn deployment-time mistakes into authoring-time errors. @allowed is your cheapest policy enforcement.

3. Secrets come from Key Vault, never parameters

Never accept a secret as a plain parameter. Reference an existing Key Vault and pull the secret via getSecret():

resource kv 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
  name: keyVaultName
  scope: resourceGroup(keyVaultRgName)
}

module sql 'br/public:avm/res/sql/server:0.10.0' = {
  name: 'sql-deployment'
  params: {
    name: sqlServerName
    location: location
    administratorLoginPassword: kv.getSecret('sql-admin-password')
  }
}

Why: Secret values passed as parameters end up in deployment history, CLI scrollback, and CI logs. getSecret() keeps them inside the ARM control plane only.

See references/SECURITY.md for managed identity patterns and OIDC federation.

4. CAF naming and mandatory tags

Follow Cloud Adoption Framework naming: <resource-type>-<workload>-<env>-<region>-<instance>. Use uniqueString() only for globally-scoped resources where collisions are real (storage accounts, Key Vaults, App Service plans hosting custom domains).

var namePrefix = 'kv-${workload}-${environment}-${location}'
var keyVaultName = '${namePrefix}-${take(uniqueString(resourceGroup().id), 4)}'

var mandatoryTags = {
  Environment: environment
  CostCenter: costCenter
  Owner: ownerEmail
  Workload: workload
  ManagedBy: 'Bicep'
}

See references/NAMING-AND-TAGGING.md for the full CAF table and tag governance.

5. Explicit targetScope, even when it's the default

Always declare targetScope at the top of the file. The default is resourceGroup, but stating it removes ambiguity for reviewers and prevents accidental scope mismatch when modules are reused.

targetScope = 'subscription'

@description('Landing zone resource group name.')
param resourceGroupName string

resource rg 'Microsoft.Resources/resourceGroups@2023-07-01' = {
  name: resourceGroupName
  location: location
  tags: mandatoryTags
}

6. Symbolic references over dependsOn

Bicep infers dependencies from symbolic references. Manual dependsOn arrays are usually a sign of a missing reference or a circular design.

// Preferred: dependency is implicit via storage.outputs.resourceId
module diagnostics 'modules/diagnostics.bicep' = {
  name: 'diag-deployment'
  params: {
    targetResourceId: storage.outputs.resourceId
    logAnalyticsWorkspaceId: laws.outputs.resourceId
  }
}

Why: Explicit dependsOn masks the actual data flow and breaks when modules are reordered or refactored.

7. Outputs are the contract, never the secret store

Outputs are read by humans and by downstream modules. They appear in deployment history. Output resource IDs, names, and endpoints. Never output a secret value. If a caller needs a secret, give them the Key Vault URI and let them call getSecret().

8. what-if before create, always

az deployment sub what-if `
  --location eastus2 `
  --template-file main.bicep `
  --parameters main.bicepparam

Read every Modify, Delete, and DeployIgnored line. what-if is the closest thing Bicep has to a dry-run, and it catches drift, accidental deletes, and parameter mistakes before they become incidents.

Workflow

When generating or reviewing Bicep, walk this loop:

1. Scope check. Confirm targetScope matches the intended deployment scope. Subscription scope for landing zones, resourceGroup for workload deployments.
2. AVM check. For every resource being created, search the AVM registry. If a module exists, use it. If it doesn't, document why a custom module is needed.
3. Parameter audit. Every param has @description. Strings have @allowed or length constraints where the value space is bounded. Secrets are @secure() and sourced from Key Vault.
4. Identity audit. No service principal secrets. Managed identities for service-to-service auth. Key Vault role assignments via AVM module's roleAssignments parameter.
5. Naming and tags. CAF naming convention. Mandatory tag set applied at the resource-group or subscription level and inherited.
6. Output audit. Outputs are minimal, named, typed, and contain no secret values.
7. Validation. Run bicep build (syntax), bicep lint (style, with bicepconfig.json), and az deployment <scope> what-if (deployment diff).
8. CI integration. Ensure the change is reachable from a GitHub Actions workflow that uses OIDC, runs what-if, requires manual approval for prod, and posts the diff to the PR.