bicep-avm-mastery（二头肌 AVM 掌握）

Skill: Bicep AVM Mastery

Azure Verified Modules (AVM), Bicep best practices, and MCP-powered infrastructure as code for Azure.

Metadata

⚠️ Staleness Watch: The AVM registry grows monthly — module counts and version numbers change frequently. Always use mcp_bicep_list_avm_metadata to enumerate current modules rather than relying on hardcoded counts. Watch for new module categories and avm/res vs avm/ptn naming changes.

Overview

Bicep is Azure's domain-specific language for infrastructure as code. This skill covers Bicep best practices, Azure Verified Modules (AVM), and MCP tool integration for high-quality, production-ready deployments.

Why Bicep?

Module 1: Bicep Best Practices

General Rules

1. Avoid setting name for module statements — no longer required
2. Use user-defined types for grouped param/output values instead of multiple params
3. Prefer .bicepparam files over JSON parameters files

Resource Patterns

// ✅ CORRECT: Use parent property
resource subnet 'Microsoft.Network/virtualNetworks/subnets@2023-09-01' = {
  parent: vnet  // Reference parent symbolically
  name: 'default'
  properties: {
    addressPrefix: '10.0.0.0/24'
  }
}

// ❌ AVOID: Slash in name property
resource subnetBad 'Microsoft.Network/virtualNetworks/subnets@2023-09-01' = {
  name: '${vnetName}/default'  // Don't do this
}

Type Safety

// ✅ CORRECT: Typed user-defined type
@export()
type storageAccountConfig = {
  @description('Storage account name')
  name: string
  @description('SKU for the storage account')
  sku: 'Standard_LRS' | 'Standard_GRS' | 'Premium_LRS'
  @description('Enable public access')
  allowPublicAccess: bool
}

// ❌ AVOID: Open types
param config object  // Too broad

Symbolic References

// ✅ CORRECT: Use symbolic references
output storageId string = storageAccount.id
output storageName string = storageAccount.name

// ❌ AVOID: resourceId() and reference()
output storageIdBad string = resourceId('Microsoft.Storage/storageAccounts', storageAccountName)

Security

// ✅ ALWAYS use @secure() for sensitive data
@secure()
param adminPassword string

@secure()
param connectionString string

Null Handling

// ✅ CORRECT: Safe dereference with coalesce
var subnetId = vnet.properties.subnets[?0].?id ?? 'default'

// ❌ AVOID: Non-null assertion or verbose ternary
var subnetIdBad = vnet!.properties.subnets[0].id

Module 2: Azure Verified Modules (AVM)

What is AVM?

Azure Verified Modules are Microsoft-supported, production-ready Bicep modules covering 328+ Azure resources. They follow best practices, are tested, and receive updates.

AVM Categories

Using AVM in Bicep

// Module from Bicep Registry (AVM)
module storageAccount 'br/public:avm/res/storage/storage-account:0.14.3' = {
  name: 'storageAccountDeployment'
  params: {
    name: 'st${uniqueString(resourceGroup().id)}'
    location: location
    skuName: 'Standard_LRS'
    kind: 'StorageV2'
    managedIdentities: {
      systemAssigned: true
    }
    networkAcls: {
      defaultAction: 'Deny'
      bypass: 'AzureServices'
    }
  }
}

Finding AVM Modules

Use the MCP tool to discover available modules:

mcp_bicep_list_avm_metadata → 328 modules with:
  - Module name and description
  - Latest version
  - Required/optional parameters
  - Usage examples

Module 3: MCP Tool Integration

Required Extensions & MCP Servers

Installation:

# VS Code Extensions (required for Bicep authoring)
code --install-extension ms-azuretools.vscode-bicep
code --install-extension ms-azuretools.vscode-azure-github-copilot
code --install-extension ms-vscode.azure-account

# MCP Server enabled via VS Code MCP gallery
# Settings: chat.mcp.gallery.enabled = true

Fallback Patterns (When MCP Unavailable)

If Bicep MCP tools are not available, use these alternatives:

Manual AVM Module Discovery:

# Search Bicep Registry for modules
az bicep registry list --resource-group bicep-registry

# Or browse AVM directly
# https://github.com/Azure/bicep-registry-modules

Available Bicep MCP Tools

Common Workflows

Find the Right AVM Module

User: "I need to deploy a storage account with private endpoints"

Alex → mcp_bicep_list_avm_metadata
  Filter: storage
  Returns: avm/res/storage/storage-account (v0.14.3)
    - Supports privateEndpoints parameter
    - Supports networkAcls
    - Includes diagnosticSettings

Get Resource Schema

User: "What properties does App Service support?"

Alex → mcp_bicep_get_az_resource_type_schema
  provider: Microsoft.Web
  resourceType: sites
  Returns: Full property schema with descriptions

Validate Before Deploy

User: "Check my Bicep file for errors"

Alex → mcp_bicep_get_bicep_file_diagnostics
  filePath: main.bicep
  Returns: BCP036 errors, warnings, suggestions

Convert Legacy ARM

User: "Convert this ARM template to Bicep"

Alex → mcp_bicep_decompile_arm_template_file
  filePath: azuredeploy.json
  Returns: Clean Bicep code

Module 4: Project Patterns

Recommended Structure

infrastructure/
├── main.bicep              # Entry point
├── main.bicepparam         # Parameters (env-specific)
├── modules/
│   ├── networking.bicep    # Custom modules
│   ├── compute.bicep
│   └── data.bicep
├── types/
│   └── shared.bicep        # Shared user-defined types
└── bicepconfig.json        # Bicep configuration

bicepconfig.json

{
  "analyzers": {
    "core": {
      "rules": {
        "no-hardcoded-location": {
          "level": "error"
        },
        "secure-parameter-default": {
          "level": "error"
        },
        "prefer-interpolation": {
          "level": "warning"
        }
      }
    }
  },
  "moduleAliases": {
    "br": {
      "public": {
        "registry": "mcr.microsoft.com/bicep"
      }
    }
  }
}

Environment-Specific Parameters

// main.bicepparam (for dev)
using './main.bicep'

param environment = 'dev'
param skuName = 'Standard_LRS'
param instanceCount = 1

// main.bicepparam (for prod)
using './main.bicep'

param environment = 'prod'
param skuName = 'Standard_GRS'
param instanceCount = 3

Module 5: Deployment Patterns

Azure CLI

# What-if preview
az deployment group what-if \
  --resource-group myRG \
  --template-file main.bicep \
  --parameters main.bicepparam

# Deploy
az deployment group create \
  --resource-group myRG \
  --template-file main.bicep \
  --parameters main.bicepparam

GitHub Actions

- name: Deploy Bicep
  uses: azure/arm-deploy@v2
  with:
    resourceGroupName: ${{ env.RESOURCE_GROUP }}
    template: ./infrastructure/main.bicep
    parameters: ./infrastructure/main.bicepparam
    deploymentMode: Incremental

Azure DevOps

- task: AzureCLI@2
  inputs:
    azureSubscription: 'AzureConnection'
    scriptType: 'bash'
    scriptLocation: 'inlineScript'
    inlineScript: |
      az deployment group create \
        --resource-group $(resourceGroup) \
        --template-file infrastructure/main.bicep \
        --parameters infrastructure/main.bicepparam

Common Diagnostic Codes

Activation Patterns

*Skill created: 2026-02-14 | Category: Cloud/Infrastructure | Status: Active | MCP-Enhanced: Yes*

Synapses

• [.github/skills/infrastructure-as-code/SKILL.md] (High, Extends, Bidirectional) - "Bicep is an IaC tool covered in depth here"
• [.github/skills/azure-architecture-patterns/SKILL.md] (High, Implements, Bidirectional) - "Bicep deploys architectures designed with WAF"
• [.github/skills/azure-devops-automation/SKILL.md] (Medium, Uses, Forward) - "CI/CD pipelines deploy Bicep code"