name: azure-verified-modules description: Azure Verified Modules (AVM) requirements and best practices for developing certified Azure Terraform modules. Use when creating or reviewing Azure modules that need AVM certification.

Azure Verified Modules (AVM) Requirements

This guide covers the mandatory requirements for Azure Verified Modules certification. These requirements ensure consistency, quality, and maintainability across Azure Terraform modules.

References:

• Azure Verified Modules
• AVM Terraform Requirements

Table of Contents

• Module Cross-Referencing
• Azure Provider Requirements
• Code Style Standards
• Variable Requirements
• Output Requirements
• Local Values Standards
• Terraform Configuration Requirements
• Testing Requirements
• Documentation Requirements
• Breaking Changes & Feature Management
• Contribution Standards
• Compliance Checklist

Module Cross-Referencing

Severity: MUST | Requirement: TFFR1

When building Resource or Pattern modules, module owners MAY cross-reference other modules. However:

• Modules MUST be referenced using HashiCorp Terraform registry reference to a pinned version
  • Example: source = "Azure/xxx/azurerm" with version = "1.2.3"
• Modules MUST NOT use git references (e.g., git::https://xxx.yyy/xxx.git or github.com/xxx/yyy)
• Modules MUST NOT contain references to non-AVM modules

Code Style Standards

Lower snake_casing

Severity: MUST | Requirement: TFNFR4

MUST use lower snake_casing for:

• Locals
• Variables
• Outputs
• Resources (symbolic names)
• Modules (symbolic names)

Example: snake_casing_example

Resource & Data Source Ordering

Severity: SHOULD | Requirement: TFNFR6

• Resources that are depended on SHOULD come first
• Resources with dependencies SHOULD be defined close to each other

Count & for_each Usage

Severity: MUST | Requirement: TFNFR7

• Use count for conditional resource creation
• MUST use map(xxx) or set(xxx) as resource's for_each collection
• The map's key or set's element MUST be static literals

Example:

resource "azurerm_subnet" "pair" {
  for_each             = var.subnet_map  # map(string)
  name                 = "${each.value}-pair"
  resource_group_name  = azurerm_resource_group.example.name
  virtual_network_name = azurerm_virtual_network.example.name
  address_prefixes     = ["10.0.1.0/24"]
}

Resource & Data Block Internal Ordering

Severity: SHOULD | Requirement: TFNFR8

Order within resource/data blocks:

1. Meta-arguments (top):

   • provider
   • count
   • for_each

2. Arguments/blocks (middle, alphabetical):

   • Required arguments
   • Optional arguments
   • Required nested blocks
   • Optional nested blocks

3. Meta-arguments (bottom):

   • depends_on
   • lifecycle (with sub-order: create_before_destroy, ignore_changes, prevent_destroy)

Separate sections with blank lines.

Module Block Ordering

Severity: SHOULD | Requirement: TFNFR9

Order within module blocks:

1. Top meta-arguments:

   • source
   • version
   • count
   • for_each

2. Arguments (alphabetical):

   • Required arguments
   • Optional arguments

3. Bottom meta-arguments:

   • depends_on
   • providers

Lifecycle ignore_changes Syntax

Severity: MUST | Requirement: TFNFR10

The ignore_changes attribute MUST NOT be enclosed in double quotes.

Good:

lifecycle {
  ignore_changes = [tags]
}

Bad:

lifecycle {
  ignore_changes = ["tags"]
}

Null Comparison for Conditional Creation

Severity: SHOULD | Requirement: TFNFR11

For parameters requiring conditional resource creation, wrap with object type to avoid "known after apply" issues during plan stage.

Recommended:

variable "security_group" {
  type = object({
    id = string
  })
  default = null
}

Dynamic Blocks for Optional Nested Objects

Severity: MUST | Requirement: TFNFR12

Nested blocks under conditions MUST use this pattern:

dynamic "identity" {
  for_each = <condition> ? [<some_item>] : []

  content {
    # block content
  }
}

Default Values with coalesce/try

Severity: SHOULD | Requirement: TFNFR13

Good:

coalesce(var.new_network_security_group_name, "${var.subnet_name}-nsg")

Bad:

var.new_network_security_group_name == null ? "${var.subnet_name}-nsg" : var.new_network_security_group_name

Provider Declarations in Modules

Severity: MUST | Requirement: TFNFR27

• provider MUST NOT be declared in modules (except for configuration_aliases)
• provider blocks in modules MUST only use alias
• Provider configurations SHOULD be passed in by module users

Local Values Standards

locals.tf Organization

Severity: MAY | Requirement: TFNFR31

• locals.tf SHOULD only contain locals blocks
• MAY declare locals blocks next to resources for advanced scenarios

Alphabetical Local Arrangement

Severity: MUST | Requirement: TFNFR32

Expressions in locals blocks MUST be arranged alphabetically.

Precise Local Types

Severity: SHOULD | Requirement: TFNFR33

Use precise types (e.g., number for age, not string).

Breaking Changes & Feature Management

Using Feature Toggles

Severity: MUST | Requirement: TFNFR34

New resources added in minor/patch versions MUST have a toggle variable to avoid creation by default:

variable "create_route_table" {
  type     = bool
  default  = false
  nullable = false
}

resource "azurerm_route_table" "this" {
  count = var.create_route_table ? 1 : 0
  # ...
}

Reviewing Potential Breaking Changes

Severity: MUST | Requirement: TFNFR35

Breaking changes requiring caution:

Resource blocks:

1. Adding new resource without conditional creation
2. Adding arguments with non-default values
3. Adding nested blocks without dynamic
4. Renaming resources without moved blocks
5. Changing count to for_each or vice versa

Variable/Output blocks:

1. Deleting/renaming variables
2. Changing variable type
3. Changing variable default values
4. Changing nullable to false
5. Changing sensitive from false to true
6. Adding variables without default
7. Deleting outputs
8. Changing output value
9. Changing output sensitive value

Contribution Standards

GitHub Repository Branch Protection

Severity: MUST | Requirement: TFNFR3

Module owners MUST set branch protection policies on the default branch (typically main):

1. Require Pull Request before merging
2. Require approval of most recent reviewable push
3. Dismiss stale PR approvals when new commits are pushed
4. Require linear history
5. Prevent force pushes
6. Not allow deletions
7. Require CODEOWNERS review
8. No bypassing settings allowed
9. Enforce for administrators

Compliance Checklist

Use this checklist when developing or reviewing Azure Verified Modules:

Module Structure

• Module cross-references use registry sources with pinned versions
• Azure providers (azurerm/azapi) versions meet AVM requirements
• .terraform-docs.yml present in module root
• CODEOWNERS file present

Code Style

• All names use lower snake_casing
• Resources ordered with dependencies first
• for_each uses map() or set() with static keys
• Resource/data/module blocks follow proper internal ordering
• ignore_changes not quoted
• Dynamic blocks used for conditional nested objects
• coalesce() or try() used for default values

Variables

• No enabled or module_depends_on variables
• Variables ordered: required (alphabetical) then optional (alphabetical)
• All variables have precise types (avoid any)
• All variables have descriptions
• Collections have nullable = false
• No sensitive = false declarations
• No default values for sensitive inputs
• Deprecated variables moved to deprecated_variables.tf

Outputs

• Outputs use anti-corruption layer pattern (discrete attributes)
• Sensitive outputs marked sensitive = true
• Deprecated outputs moved to deprecated_outputs.tf

Terraform Configuration

• terraform.tf has version constraints (~> format)
• required_providers block present with all providers
• No provider declarations in module (except aliases)
• Locals arranged alphabetically

Testing & Quality

• Required testing tools configured
• New resources have feature toggles
• Breaking changes reviewed and documented

Summary Statistics

• Functional Requirements: 3
• Non-Functional Requirements: 34
• Total Requirements: 37

By Severity

• MUST: 21 requirements
• SHOULD: 14 requirements
• MAY: 2 requirements

Based on: Azure Verified Modules - Terraform Requirements