2103 Adr 003 Avm First Approach 50944ee5

ADR-003: Azure Verified Modules (AVM) First Approach

Status

Accepted

Date

2024-01-15

Context

When generating Bicep infrastructure code, there are multiple approaches to resource definition:

1. Raw Bicep resources - Define each Azure resource directly with full property specification
2. Custom modules - Create reusable modules with organization-specific patterns
3. Azure Verified Modules (AVM) - Use Microsoft's officially maintained module library

The Challenge

Azure resources have complex configurations with hundreds of potential properties. A single App Service deployment might require:

• App Service Plan (with SKU, workers, zone redundancy)
• App Service (with runtime, networking, identity, slots)
• Private Endpoint (with DNS, NIC, subnet)
• Diagnostic Settings (with log categories, metrics)
• Managed Identity (with role assignments)

Writing raw Bicep for each resource is:

• Time-consuming and error-prone
• Inconsistent across teams
• Difficult to maintain as Azure APIs evolve
• Missing security best practices

Decision

We adopted an AVM-first approach where:

1. Prefer AVM modules for all supported resources
2. Fall back to raw Bicep only when AVM doesn't cover the resource type
3. Use consistent parameter patterns across all module calls
4. Document AVM versions in planning files for reproducibility

AVM Module Categories

Standard Module Reference Format

module keyVault 'br/public:avm/res/key-vault/vault:0.11.0' = {
  name: 'keyVaultDeployment'
  params: {
    name: keyVaultName
    location: location
    tags: tags
    // AVM handles: private endpoints, RBAC, diagnostics, soft delete
    enablePurgeProtection: true
    enableSoftDelete: true
    softDeleteRetentionInDays: 90
  }
}

Why AVM?

1. Microsoft maintained - Updated with latest API versions and security patches
2. Well-Architected by design - Implements WAF recommendations out of the box
3. Tested extensively - Unit tests, integration tests, policy compliance
4. Consistent interfaces - Similar parameter patterns across all modules
5. Private endpoint support - Built-in PE configuration for supported resources

Consequences

Positive

• 60-80% reduction in Bicep code volume
• Security best practices included by default (TLS 1.2, HTTPS, encryption)
• Easier maintenance as AVM handles API version updates
• Consistent module interface patterns improve learning curve
• Private endpoints and diagnostics are first-class features

Negative

• Learning curve for AVM parameter structure
• Module versions must be tracked and updated
• Some edge-case configurations may not be exposed
• Dependency on external registry (mcr.microsoft.com)
• Raw Bicep still needed for unsupported resource types

Mitigations

• Agent prompts include common AVM patterns
• Planning files document specific versions to use
• Fallback to raw Bicep is explicitly allowed
• Shared configuration includes AVM module references

Implementation in Agents

bicep-plan Agent

Creates planning documents that specify:

• Which AVM modules to use
• Specific versions (e.g., 0.11.0)
• Required parameters for each module
• Dependencies between modules

bicep-code Agent

Generates Bicep code that:

• References AVM modules from public registry
• Uses pinned versions from planning docs
• Follows AVM parameter naming conventions
• Includes proper outputs for module chaining

AVM Resources

• AVM Module Index - Searchable module catalog
• AVM GitHub - Source code
• AVM Contribution Guide - Module development

Common AVM Modules Used

Note: Versions shown are examples. Always check AVM Index for latest.

References

• .github/agents/_shared/defaults.md - Shared AVM references
• .github/agents/bicep-plan.agent.md - Planning agent
• .github/agents/bicep-code.agent.md - Implementation agent