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:

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

github.com/xxx/yyy

)

Modules MUST NOT contain references to non-AVM modules

Azure Provider Requirements

Severity: MUST | Requirement: TFFR3

Authors MUST only use the following Azure providers:

Provider	Min Version	Max Version
azapi	>= 2.0	< 3.0
azurerm	>= 4.0	< 5.0

Requirements:

Authors MAY select either Azurerm, Azapi, or both providers
MUST use
```
required_providers
```
block to enforce provider versions
SHOULD use pessimistic version constraint operator (
```
~>
```
)

Example:

hcl

terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
    azapi = {
      source  = "Azure/azapi"
      version = "~> 2.0"
    }
  }
}

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:

hcl

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:

Meta-arguments (top):
- ```
provider
```
- ```
count
```
- ```
for_each
```
Arguments/blocks (middle, alphabetical):
- Required arguments
- Optional arguments
- Required nested blocks
- Optional nested blocks

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:

Top meta-arguments:
- ```
source
```
- ```
version
```
- ```
count
```
- ```
for_each
```
Arguments (alphabetical):
- Required arguments
- Optional arguments
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:

hcl

lifecycle {
  ignore_changes = [tags]
}

Bad:

hcl

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:

hcl

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:

hcl

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

  content {
    # block content
  }
}

Default Values with coalesce/try

Severity: SHOULD | Requirement: TFNFR13

Good:

hcl

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

Bad:

hcl

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

Variable Requirements

Not Allowed Variables

Severity: MUST | Requirement: TFNFR14

Module owners MUST NOT add variables like

enabled

module_depends_on

to control entire module operation. Boolean feature toggles for specific resources are acceptable.

Variable Definition Order

Severity: SHOULD | Requirement: TFNFR15

Variables SHOULD follow this order:

All required fields (alphabetical)
All optional fields (alphabetical)

Variable Naming Rules

Severity: SHOULD | Requirement: TFNFR16

Follow HashiCorp's naming rules
Feature switches SHOULD use positive statements:
```
xxx_enabled
```
instead of
```
xxx_disabled
```

Variables with Descriptions

Severity: SHOULD | Requirement: TFNFR17

```
description
```
SHOULD precisely describe the parameter's purpose and expected data type
Target audience is module users, not developers
For
```
object
```
types, use HEREDOC format

Variables with Types

Severity: MUST | Requirement: TFNFR18

```
type
```
MUST be defined for every variable
```
type
```
SHOULD be as precise as possible
```
any
```
MAY only be used with adequate reasons
Use
```
bool
```
instead of
```
string
```
/
```
number
```
for true/false values
Use concrete
```
object
```
instead of
```
map(any)
```

Sensitive Data Variables

Severity: SHOULD | Requirement: TFNFR19

If a variable's type is

object

and contains sensitive fields, the entire variable SHOULD be

sensitive = true

, or extract sensitive fields into separate variables.

Non-Nullable Defaults for Collections

Severity: SHOULD | Requirement: TFNFR20

Nullable SHOULD be set to

false

for collection values (sets, maps, lists) when using them in loops. For scalar values, null may have semantic meaning.

Discourage Nullability by Default

Severity: MUST | Requirement: TFNFR21

nullable = true

MUST be avoided unless there's a specific semantic need for null values.

Avoid sensitive = false

Severity: MUST | Requirement: TFNFR22

sensitive = false

MUST be avoided (this is the default).

Sensitive Default Value Conditions

Severity: MUST | Requirement: TFNFR23

A default value MUST NOT be set for sensitive inputs (e.g., default passwords).

Handling Deprecated Variables

Severity: MUST | Requirement: TFNFR24

Move deprecated variables to
```
deprecated_variables.tf
```
Annotate with
```
DEPRECATED
```
at the beginning of description
Declare the replacement's name
Clean up during major version releases

Output Requirements

Additional Terraform Outputs

Severity: SHOULD | Requirement: TFFR2

Authors SHOULD NOT output entire resource objects as these may contain sensitive data and the schema can change with API or provider versions.

Best Practices:

Output computed attributes of resources as discrete outputs (anti-corruption layer pattern)
SHOULD NOT output values that are already inputs (except
```
name
```
)
Use
```
sensitive = true
```
for sensitive attributes
For resources deployed with
```
for_each
```
, output computed attributes in a map structure

Examples:

hcl

# Single resource computed attribute
output "foo" {
  description = "MyResource foo attribute"
  value       = azurerm_resource_myresource.foo
}

# for_each resources
output "childresource_foos" {
  description = "MyResource children's foo attributes"
  value = {
    for key, value in azurerm_resource_mychildresource : key => value.foo
  }
}

# Sensitive output
output "bar" {
  description = "MyResource bar attribute"
  value       = azurerm_resource_myresource.bar
  sensitive   = true
}

Sensitive Data Outputs

Severity: MUST | Requirement: TFNFR29

Outputs containing confidential data MUST be declared with

sensitive = true

Handling Deprecated Outputs

Severity: MUST | Requirement: TFNFR30

Move deprecated outputs to
```
deprecated_outputs.tf
```
Define new outputs in
```
outputs.tf
```
Clean up during major version releases

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

Terraform Configuration Requirements

Terraform Version Requirements

Severity: MUST | Requirement: TFNFR25

terraform.tf
requirements:

MUST contain only one
```
terraform
```
block
First line MUST define
```
required_version
```
MUST include minimum version constraint
MUST include maximum major version constraint
SHOULD use
```
~> #.#
```
or
```
>= #.#.#, < #.#.#
```
format

Example:

hcl

terraform {
  required_version = "~> 1.6"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.0"
    }
  }
}

Providers in required_providers

Severity: MUST | Requirement: TFNFR26

```
terraform
```
block MUST contain
```
required_providers
```
block
Each provider MUST specify
```
source
```
and
```
version
```
Providers SHOULD be sorted alphabetically
Only include directly required providers
```
source
```
MUST be in format
```
namespace/name
```
```
version
```
MUST include minimum and maximum major version constraints
SHOULD use
```
~> #.#
```
or
```
>= #.#.#, < #.#.#
```
format

Testing Requirements

Test Tooling

Severity: MUST | Requirement: TFNFR5

Required testing tools for AVM:

Terraform (
```
terraform validate/fmt/test
```
)
terrafmt
Checkov
tflint (with azurerm ruleset)
Go (optional for custom tests)

Test Provider Configuration

Severity: SHOULD | Requirement: TFNFR36

For robust testing,

prevent_deletion_if_contains_resources

SHOULD be explicitly set to

false

in test provider configurations.

Documentation Requirements

Module Documentation Generation

Severity: MUST | Requirement: TFNFR2

Documentation MUST be automatically generated via Terraform Docs
A
```
.terraform-docs.yml
```
file MUST be present in the module root

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:

hcl

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:

Adding new resource without conditional creation
Adding arguments with non-default values
Adding nested blocks without
```
dynamic
```
Renaming resources without
```
moved
```
blocks
Changing
```
count
```
to
```
for_each
```
or vice versa

Variable/Output blocks:

Deleting/renaming variables
Changing variable
```
type
```
Changing variable
```
default
```
values
Changing
```
nullable
```
to false
Changing
```
sensitive
```
from false to true
Adding variables without
```
default
```
Deleting outputs
Changing output
```
value
```
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

Require Pull Request before merging
Require approval of most recent reviewable push
Dismiss stale PR approvals when new commits are pushed
Require linear history
Prevent force pushes
Not allow deletions
Require CODEOWNERS review
No bypassing settings allowed
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

azure-verified-modules

NPX Install

Tags

SKILL.md Content

Azure Verified Modules (AVM) Requirements

Table of Contents

Module Cross-Referencing

Azure Provider Requirements

Code Style Standards

Lower snake_casing

Resource & Data Source Ordering

Count & for_each Usage

Resource & Data Block Internal Ordering

Module Block Ordering

Lifecycle ignore_changes Syntax

Null Comparison for Conditional Creation

Dynamic Blocks for Optional Nested Objects

Default Values with coalesce/try

Provider Declarations in Modules

Variable Requirements

Not Allowed Variables

Variable Definition Order

Variable Naming Rules

Variables with Descriptions

Variables with Types

Sensitive Data Variables

Non-Nullable Defaults for Collections

Discourage Nullability by Default

Avoid sensitive = false

Sensitive Default Value Conditions

Handling Deprecated Variables

Output Requirements

Additional Terraform Outputs

Sensitive Data Outputs

Handling Deprecated Outputs

Local Values Standards

locals.tf Organization

Alphabetical Local Arrangement

Precise Local Types

Terraform Configuration Requirements

Terraform Version Requirements

Providers in required_providers

Testing Requirements

Test Tooling

Test Provider Configuration

Documentation Requirements

Module Documentation Generation

Breaking Changes & Feature Management

Using Feature Toggles

Reviewing Potential Breaking Changes

Contribution Standards

GitHub Repository Branch Protection

Compliance Checklist

Module Structure

Code Style

Variables

Outputs

Terraform Configuration

Testing & Quality

Summary Statistics

By Severity