Azure Verified Modules (AVM) - Terraform Instructions

Overview

This repository contains an Azure Verified Module for Terraform. AVM modules are reusable, tested Azure infrastructure modules that follow the published AVM specifications.

AVM has three module classifications:

• Resource modules - one primary Azure resource and its child or extension resources.
• Pattern modules - opinionated multi-resource solutions composed from resource modules.
• Utility modules - shared logic or interfaces that do not directly deploy an Azure resource.

Use the AVM Terraform agent for specification-driven module development. AGENTS.md is a compatibility entry point for agents that do not load this Copilot-specific file directly.

Critical Compliance Requirements

Instruction acknowledgement

After reading these instructions and the relevant skills, but before modifying files, output this block visibly to the user:

{
  "avm-terraform-instructions": "loaded",
  "skills": ["<loaded-skill-name>"]
}

List every skill loaded for the task. Use an empty skills array when no specialized skill applies.

Follow current AVM specifications

Before reviewing or generating Terraform:

1. Fetch https://azure.github.io/Azure-Verified-Modules/llms.txt.
2. Locate and read the current raw page for every relevant Terraform and shared specification.
3. Read the complete skill matching the task.
4. Resolve conflicts in favor of the current published specification.

Do not cite a specification from memory or treat an older module as authoritative.

Use AzAPI for managed authoring

New AVM Terraform modules use Azure/azapi for every control-plane resource and every supported direct Azure operation. Do not use hashicorp/azurerm for convenience, ordinary supporting infrastructure, examples, tests, or fixtures.

AzureRM is permitted only for a specifically documented data-plane or non-ARM operation that AzAPI cannot perform. Each exception must be independently justified and must not authorize other AzureRM usage. Read avm-tf-azapi and avm-tf-tflint before implementing an exception.

Generate documentation

Do not hand-edit generated README.md files. Author module content in _header.md and _footer.md, then run avm docs or avm pre-commit. Read avm-tf-documentation before changing module documentation.

Use the Managed Toolchain

Use PowerShell 7.4 or later with Avm.Authoring from Microsoft Artifact Registry (MAR). MAR is not registered by default. Follow the PSResourceGet 1.2.0 prerequisite, then register MAR once:

Import-Module Microsoft.PowerShell.PSResourceGet -MinimumVersion 1.2.0
Register-PSResourceRepository -Name MAR `
    -Uri 'https://mcr.microsoft.com' `
    -ApiVersion ContainerRegistry `
    -Trusted
Install-PSResource -Name avm.authoring `
    -Repository MAR `
    -Scope CurrentUser
Import-Module Avm.Authoring
avm version

To update from MAR, repeat Install-PSResource with -Reinstall, then start a new PowerShell session and import the module. The built-in avm update still uses PowerShell Gallery. Do not substitute the retired Make, Porch, container, or repository-launcher workflows.

Module Discovery

Use the current AVM indexes to confirm module availability, classification, naming, and ownership:

• Terraform resource modules
• Terraform pattern modules
• Terraform utility modules

New repositories use terraform-azure-avm-<class>-<name> and publish under the Azure Terraform Registry namespace with the /azure system identifier. Existing legacy repository and Registry names do not permit AzureRM use.

Quality Assurance

• Keep reusable modules free of provider configuration blocks.
• Use PowerShell for supported hooks and scripts.
• Add or update the smallest relevant unit, integration, or E2E coverage.
• Run avm pre-commit and review generated changes.
• Commit the complete worktree before running avm pr-check.
• Treat TFLint and Conftest exceptions as reviewed deviations, not shortcuts around a failing check.

Skills

When a task falls within a skill's domain, read and follow the full skill before proceeding.