Prerequisites

GitHub Account

To contribute, you need a GitHub account. If you are a Microsoft employee, your account must be linked to your corporate identity and you must be a member of the Azure organization.

Module Owner Access (Microsoft FTEs only)

Access for Terraform module owners is granted via the Azure Verified Modules (AVM) Module Contributors Entra access package. Request access here:

• Azure Verified Modules (AVM) Module Contributors — Access Package

Once approved, you will be added to the azure-verified-modules-module-contributors Entra group, which is the source of truth for who is authorized to own and approve changes on AVM Terraform module repositories.

Required Tooling

• Git

  git config --global user.name "Your Name"
  git config --global user.email "you@example.com"

• PowerShell 7.4 or later

• Avm.Authoring

  Install-PSResource Avm.Authoring
  Import-Module Avm.Authoring
  avm doctor

  Install-Module Avm.Authoring -Scope CurrentUser remains available for environments that use PowerShellGet v2. Run avm update to upgrade an existing installation. The module downloads, verifies, and caches its managed tools, including Terraform, on demand. Run avm doctor --install to preload every supported tool. Docker and Podman are not required.

• Azure CLI

• Visual Studio Code

  • HashiCorp Terraform extension
  • Microsoft Azure Terraform extension
  • EditorConfig extension

Terraform Contribution Flow

This guide covers the end-to-end contribution flow for AVM Terraform modules.
Whether you are a module owner or an external contributor, the core workflow is the same — the key differences are called out using tabs below.

Prerequisites

Install PowerShell 7.4 or later, start pwsh, and install the Avm.Authoring module:

Install-PSResource Avm.Authoring
Import-Module Avm.Authoring

Install-Module Avm.Authoring -Scope CurrentUser is also supported for environments that use PowerShellGet v2. Run avm with no arguments to list the supported verbs, then verify the installed version and diagnose your local environment:

avm
avm version
avm doctor

Run avm update whenever a newer Avm.Authoring release is available. Avm.Authoring downloads, verifies, and caches Terraform, TFLint, terraform-docs, Conftest, and mapotf on demand. Docker or Podman is not required. You can inspect or manage the tool cache:

avm tool list
avm tool which terraform
avm tool install terraform
avm doctor --install

Overview

---
config:
  nodeSpacing: 20
  rankSpacing: 20
  diagramPadding: 50
  padding: 5
  flowchart:
    wrappingWidth: 300
    padding: 5
  layout: elk
  elk:
    mergeEdges: true
    nodePlacementStrategy: LINEAR_SEGMENTS
---

flowchart TD
  Z("1 - Fork [optional]")
    click Z "#1-fork-optional"
  A(2 - Branch)
    click A "#2-branch"
  B(3 - Implement your code change)
    click B "#3-implement-your-code-change"
  C(4 - Run avm pre-commit)
    click C "#4-run-avm-pre-commit"
  C2(5 - Run pr-check and test tiers locally)
    click C2 "#5-run-pr-check-and-test-tiers-locally"
  D(6 - Raise or Update PR)
    click D "#6-raise-or-update-pr"
  E("7 - Approve and monitor CI tests [owner]")
    click E "#7-approve-and-monitor-ci-tests"
  F{Tests passing?}
  G(8 - Review and merge PR)
    click G "#8-review-and-merge-pr"
  H(9 - Cut a release)
    click H "#9-cut-a-release"
  Z --> A
  A --> B
  B --> C
  C --> C2
  C2 --> D
  D --> E
  E --> F
  F -->|no| B
  F -->|yes| G
  G --> H

1. Fork [optional]

A fork is your own copy of the repository under your GitHub account. It lets you make changes without needing write access to the upstream repo. Once your changes are ready, you raise a pull request from your fork back to the original repository.

git remote add upstream https://github.com/Azure/terraform-azure-avm-res-<rp>-<modulename>.git
git fetch upstream
git checkout main
git merge upstream/main

gh repo fork Azure/terraform-azure-avm-res-<rp>-<modulename> --clone
cd terraform-azure-avm-res-<rp>-<modulename>

git remote -v
# origin    https://github.com/<your-username>/terraform-azure-avm-res-<rp>-<modulename>.git (fetch)
# upstream  https://github.com/Azure/terraform-azure-avm-res-<rp>-<modulename>.git (fetch)

2. Branch

Create a branch from main to work on your changes:

git checkout -b <your-branch-name>

If this is a new module and the repository does not exist yet, module owners should first follow the Repository Creation Process.

3. Implement your code change

Before writing code, review the Terraform specifications and composition guidelines to ensure your contribution complies with AVM’s design principles.

Once you’ve made your changes, stage, commit, and push them:

git add -A
git commit -m "feat: description of your change"
git push

Lifecycle hooks

Some examples need setup work before Terraform runs — deploying prerequisites, generating a terraform.tfvars, or seeding a random prefix. AVM supports optional hook scripts for this:

The terraform unit test engine runs PowerShell hooks only.
Refactor these shell hooks to '.ps1': tests/unit/setup.sh

Each hook runs in its own isolated pwsh subprocess, so environment variables it exports do not reach subsequent Terraform commands. An e2e pre.ps1 can pass values by writing KEY=VALUE lines to examples/<name>/.env; the runner reads the file after the hook and passes the values to the example’s Terraform subprocesses. A unit or integration setup.ps1 uses a .env file at its target root: the repository root or modules/<name>/. For these test hooks, the .env file is two directories above setup.ps1, not beside it.

Because hooks are invoked from an isolated process, anchor paths on $PSScriptRoot rather than relying on the current working directory. Note also that PowerShell does not stop on a failed native command the way set -e does in bash — check $LASTEXITCODE after each Terraform call and throw so a failed hook surfaces immediately instead of later as a confusing downstream error.

4. Run avm pre-commit

Before raising a pull request, run pre-commit to update your files:

avm pre-commit

For Terraform modules, this command:

1. Synchronizes the centrally governed managed files, which can add, update, or remove files.
2. Applies deterministic fixes for AVM convention rules.
3. Runs mapotf transformations.
4. Formats Terraform files.
5. Regenerates documentation.

The command intentionally updates the working tree. Review every change it makes, then commit and push again:

git add -A
git commit -m "chore: pre-commit fixes"
git push

5. Run pr-check and test tiers locally

After committing the pre-commit changes, run the broader pull request checks:

az login
avm pr-check

avm pr-check requires a clean Git working tree and Azure credentials because its Conftest policy checks create Terraform plans for the examples. It checks managed-file, formatting, and transformation drift, then runs TFLint, Conftest policy checks, AVM convention checks, terraform validate, and documentation drift checks. It does not run the Terraform test tiers; those remain separate commands so failures are reported independently.

Unit testing

AVM convention checks require a unit test fixture under tests/unit. Use mocked providers to keep unit tests fast and free of external dependencies:

avm test unit

The command also runs unit test tiers found under direct modules/<name>/ submodules.

Integration testing

Integration tests under tests/integration deploy real resources and require Azure credentials:

az login
avm test integration

The command also runs integration test tiers found under direct modules/<name>/ submodules. A repository without integration tests reports the tier as skipped rather than passed.

Local e2e testing

Run the e2e test tier to deploy, check idempotency, and destroy resources for each example:

az login
avm test e2e

This tier requires real Azure credentials. Azure CLI authentication is sufficient for local development; no environment variables or service principals are needed. To run one example while iterating:

avm test e2e --example <name>

An example containing .e2eignore is excluded. Apply failures caused by transient region, SKU capacity, or quota errors are destroyed and retried up to two times by default; use -MaxRetry 0 to disable retries.

Local e2e testing is especially useful for external contributors, since only module owners can approve credentialed CI e2e runs.

6. Raise or Update PR

7. Approve and monitor CI tests

Once a PR is created, CI workflows are triggered automatically. A centrally managed Azure test subscription is provided for credentialed jobs, so contributors do not configure CI credentials themselves.

What CI runs

The centrally managed workflow keeps validation and test tiers in separate jobs so a failure produces an actionable signal:

• PR validation — runs the equivalent of avm pr-check: managed-file and generated-file drift checks, Terraform formatting, mapotf transformations, TFLint, Conftest policy checks, AVM convention checks, terraform validate, and documentation checks.
• Unit tests — runs avm test unit.
• Integration tests — runs avm test integration when the repository has integration tests.
• End-to-end tests — discovers runnable examples and tests each example independently with the equivalent of avm test e2e --example <name>.

Each e2e job deploys the example, checks idempotency with terraform plan, and destroys the resources. Examples containing .e2eignore are excluded.

If tests fail

Go back to step 3 — fix the issue, run avm pre-commit again, push your changes, and the CI tests will re-run automatically on the same PR.

Running e2e for external contributions

When approving a PR from an external contributor:

1. Review the code for security — check for any malicious code or changes to workflow files before running tests. If found, close the PR and report the contributor.
2. Create a release branch from main (e.g. release/<description>).
3. Change the PR’s base branch to the release branch and merge it.
4. Create a new PR from the release branch to main — this triggers the validation and test jobs.
5. Approve the run and wait for results.
6. If tests fail, send back to the contributor to fix and repeat from step 3.

Running e2e for your own contributions

For your own PRs, the tests trigger automatically — approve the run and wait for results.

8. Review and merge PR

Finding an approver

1. First port of call — find a friendly module owner. Look up another active Terraform module owner from the azure-verified-modules-module-contributors Entra group and request a review from them directly. This is the fastest path to approval.
2. If no module owner is available, fall back to the AVM core team:
   • Assign the @Azure/azure-verified-modules-engineering-owners GitHub team as a reviewer on the PR.
   • Apply the  Needs: Core Team 🧞  label so the request is picked up during core team triage.

9. Cut a release

After the PR is merged to main, create a release via GitHub Releases:

1. Go to the Releases tab and click Draft a new release.
2. Set Target to the main branch.
3. Type a new tag (e.g. v0.1.0 for first publish, or increment for subsequent releases). Tags MUST include the v prefix.
4. Use Generate release notes and credit external contributors.
5. Click Publish release.

First module publish

For a brand new module, contact the AVM core team (e.g. via the AVM - Module Triage project) to request initial publication to the HashiCorp Registry. Subsequent releases are published automatically.

Common mistakes to avoid

• Search and update TODO comments that come from the template — remove them once addressed.
• Do not commit terraform.lock.hcl — it is excluded by .gitignore.
• Update _header.md and SUPPORT.md.
• Do not commit terraform.tfvars files.
• Do not commit .env files created by lifecycle hooks.
• Do not add shell (.sh) lifecycle hooks — see Lifecycle hooks.

Terraform Composition

Repositories

Each Terraform AVM module will have its own GitHub Repository in the Azure GitHub Organization as per SNFR19.

This repo will be created by the Module Owners and the AVM Core team collaboratively, including the configuration of permissions as per SNFR9

Directory and File Structure

Below is the directory and file structure expected for each AVM Terraform repository/module.
See the Terraform AVM template repository.

• tests/ - (for unit tests and integration tests using Terraform test)
  • unit/ - (.tftest.hcl files for required unit testing with Terraform test)
    • setup.ps1 - (optional setup hook)
  • integration/ - (optional .tftest.hcl files for integration testing with Terraform test)
    • setup.ps1 - (optional setup hook)
• modules/ - (for sub-modules only if used)
• examples/ - (all examples must deploy successfully without requiring input - these are customer facing)
  • <at least one folder> - (at least one example that uses the variable defaults minimum/required parameters/variables only)
    • pre.ps1 - (optional setup hook)
    • post.ps1 - (optional cleanup hook)
    • tflint-pre.ps1 - (optional setup hook for TFLint)
    • .e2eignore - (optional marker that excludes the example from e2e testing)
  • <other folders for examples as required>
• /... - (Module files that live in the root of module directory)
  • _header.md - (required for documentation generation)
  • _footer.md - (required for documentation generation)
  • main.tf
  • locals.tf
  • variables.tf
  • outputs.tf
  • terraform.tf
  • README.md (autogenerated)
  • main.resource1.tf (If a larger module you may chose to use dot notation for each resource)
  • locals.resource1.tf

See Lifecycle hooks for hook execution, environment, and migration guidance.

Code Styling

This section points to conventions to be followed when developing a module.

Casing

Use snake_casing as per TFNFR3.

Input Parameters and Variables

Make sure to review all specifications of Category: Inputs/Outputs within the Terraform specification pages.

Resources

Resources are primarily leveraged by resource modules to declare the primary resource of the main resource type deployed by the AVM module.

Make sure to review all specifications covering resource properties and usage.

Outputs

Make sure to review all specifications of Category: Inputs/Outputs within the Terraform specification pages.

Interfaces

To meet RMFR4 and RMFR5 AVM resource modules must leverage consistent interfaces for all the optional features/extension resources supported by the AVM module primary resource.

Please refer to the Terraform Interfaces page.

Required AzAPI patterns

Every Terraform AVM resource module MUST implement the following AzAPI patterns. The cross-references point at the normative specs — this section only summarises them so that nothing here is missed during scaffolding.

The interface schema files under static/includes/interfaces/tf/ are the canonical, copy-pasteable templates for the variables described by these specs. Treat them as authoritative.

Telemetry

To meet the requirements of SFR3 & SFR4, we use the modtm telemetry provider. This lightweight telemetry provider sends telemetry data to Azure Application Insights via a HTTP POST front end service.

The modtm telemetry provider is included in all Terraform modules and is enabled by default through the main.telemetry.tf file being automatically distributed from the template repo. You do not need to change this configuration.

Make sure that the modtm provider is listed under the required_providers section in the module’s terraform.tf file using the following entry. This is also validated by the linter.

terraform {
  required_providers {
    # .. other required providers as needed
    modtm = {
      source = "Azure/modtm"
      version = "~> 0.3"
    }
  }
}

Review of Terraform Modules

The AVM module review is a critical step before an AVM Terraform module gets published to the Terraform Registry and made publicly available for customers, partners and wider community to consume and contribute to. It serves as a quality assurance step to ensure that the AVM Terraform module complies with the Terraform specifications of AVM. The below process outlines the steps that both the module owner and module reviewer need to follow.

1. The module owner completes the development of the module in their branch or fork.

2. The module owner submits a pull request (PR) titled AVM-Review-PR and ensures that all checks are passing on that PR as that is a pre-requisite to request a review.

3. The module owner assigns the @Azure/azure-verified-modules-engineering-owners GitHub team as reviewer on the PR.

4. The module owner leaves the following comment as it is on the module proposal in the AVM - Module Triage project by searching for their module proposal by name there.

   ➕ AVM Terraform Module Review Request

   I have completed my initial development of the module and I would like to request a review of my module before publishing it to the Terraform Registry. The latest code is in a PR titled [AVM-Review-PR](REPLACE WITH URL TO YOUR PR) on the module repo and all checks on that PR are passing.

5. The AVM team moves the module proposal from “In Development” to “In Review” in the AVM - Module Triage project.

6. The AVM team will assign a module reviewer who will open a blank issue on the module titled “AVM-Review” and populate it with the below mark down. This template already marks the specs as compliant which are covered by the checks that run on the PR. There are some specs which don’t need to be checked at the time of publishing the module therefore they are marked as NA.

   ➕ AVM Terraform Module Review Issue

   Dear module owner,

   As per the module ownership requirements and responsibilities at the time of [assignment](REPLACE WITH THE LINK TO THE AVM MODULE PROPOSAL), the AVM Team is opening this issue, requesting you to validate your module against the below AVM specifications and confirm its compliance.

   Please don’t close this issue and merge your AVM-Review-PR until advised to do so. This review is a prerequisite for publishing your module’s v0.1.0 in the Terraform Registry. The AVM team is happy to assist with any questions you might have.

   Requested Actions

   1. Complete the below task list by ticking off the tasks.
   2. Complete the below table by updating the Compliant column with Yes, No or NA as possible values.

   Please use the comments columns to provide additional details especially if the Compliant column is updated to No or NA.

   Tasks

   • Address comments on AVM-Review-PR if any
   • Ensure that all checks on AVM-Review-PR are passing
   • Make sure you have run avm pre-commit.
   • Tick this to acknowledge specs with comment “Module Owner to action this spec post-publish as appropriate” in the table below.
   • Please update the _header.md file as it contains instructions which - once actioned - need to be replaced with Module Name and Description.

   ID	Spec	Compliant	Comments
   1	ID: SFR1 - Category: Composition - Preview Services		NA if no preview services are used
   2	ID: SFR2 - Category: Composition - WAF Aligned		Ensure only high priority reliability & security recommendations are implemented if any
   3	ID: SFR3 - Category: Telemetry - Deployment/Usage Telemetry
   4	ID: SFR4 - Category: Telemetry - Telemetry Enablement Flexibility	Yes	Yes if AVM Template Repo has been used
   5	ID: SFR5 - Category: Composition - Availability Zones
   6	ID: SFR6 - Category: Composition - Data Redundancy
   7	ID: SNFR25 - Category: Composition - Resource Naming
   8	ID: SNFR1 - Category: Testing - Prescribed Tests	Yes	Yes if all e2e test, version-check & linting checks passed
   9	ID: SNFR2 - Category: Testing - E2E Testing	Yes	Yes if e2e tests passed
   10	ID: SNFR3 - Category: Testing - AVM Compliance Tests	Yes	Yes if all e2e test, version-check & linting checks passed
   11	ID: SNFR4 - Category: Testing - Unit Tests		NA if no tests created in tests folder
   12	ID: SNFR5 - Category: Testing - Upgrade Tests	NA	Module Owner to action this spec post-publish as appropriate
   13	ID: SNFR6 - Category: Testing - Static Analysis/Linting Tests	Yes	Yes if all linting checks passed
   14	ID: SNFR7 - Category: Testing - Idempotency Tests	Yes	Yes if e2e tests passed
   15	ID: SNFR24 - Category: Testing - Testing Child, Extension & Interface Resources	Yes	Yes if e2e tests passed
   16	ID: SNFR8 - Category: Contribution/Support - Module Owner(s) GitHub
   17	ID: SNFR20 - Category: Contribution/Support - GitHub Teams Only
   18	ID: SNFR9 - Category: Contribution/Support - AVM & PG Teams GitHub Repo Permissions
   19	ID: SNFR10 - Category: Contribution/Support - MIT Licensing	Yes	Yes if AVM Template Repo has been used
   20	ID: SNFR11 - Category: Contribution/Support - Issues Response Times	NA	Module Owner to action this spec post-publish as appropriate
   21	ID: SNFR12 - Category: Contribution/Support - Versions Supported	NA	Module Owner to action this spec post-publish as appropriate
   22	ID: SNFR23 - Category: Contribution/Support - GitHub Repo Labels
   23	ID: SNFR14 - Category: Inputs - Data Types
   24	ID: SNFR22 - Category: Inputs - Parameters/Variables for Resource IDs
   25	ID: SNFR15 - Category: Documentation - Automatic Documentation Generation	Yes	Yes if linting / docs check passed
   26	ID: SNFR16 - Category: Documentation - Examples/E2E	Yes	Yes if e2e tests passed
   27	ID: SNFR17 - Category: Release - Semantic Versioning	Yes	Yes if version-check check passed
   28	ID: SNFR18 - Category: Release - Breaking Changes	NA	Module Owner to action this spec post-publish as appropriate
   29	ID: SNFR19 - Category: Publishing - Registries Targeted	NA	Module Owner to action this spec post-publish as appropriate
   30	ID: SNFR21 - Category: Publishing - Cross Language Collaboration	NA	Module Owner to action this spec post-publish as appropriate
   31	ID: RMFR1 - Category: Composition - Single Resource Only
   32	ID: RMFR2 - Category: Composition - No Resource Wrapper Modules
   33	ID: RMFR3 - Category: Composition - Resource Groups
   34	ID: RMFR4 - Category: Composition - AVM Consistent Feature & Extension Resources Value Add	Yes	Yes if linting / terraform check passed
   35	ID: RMFR5 - Category: Composition - AVM Consistent Feature & Extension Resources Value Add Interfaces/Schemas	Yes	Yes if linting / terraform check passed
   36	ID: RMFR8 - Category: Composition - Dependency on child and other resources
   37	ID: RMFR6 - Category: Inputs - Parameter/Variable Naming
   38	ID: RMFR7 - Category: Outputs - Minimum Required Outputs	Yes	Yes if linting / terraform check passed
   39	ID: RMNFR1 - Category: Naming - Module Naming
   40	ID: RMNFR2 - Category: Inputs - Parameter/Variable Naming
   41	ID: RMNFR3 - Category: Composition - RP Collaboration	NA	Module Owner to action this spec post-publish as appropriate
   42	ID: PMFR1 - Category: Composition - Resource Group Creation		NA if this is not a pattern module
   43	ID: PMNFR1 - Category: Naming - Module Naming		NA if this is not a pattern module
   44	ID: PMNFR2 - Category: Composition - Use Resource Modules to Build a Pattern Module		NA if this is not a pattern module
   45	ID: PMNFR3 - Category: Composition - Use other Pattern Modules to Build a Pattern Module		NA if this is not a pattern module
   46	ID: PMNFR4 - Category: Hygiene - Missing Resource Module(s)		NA if this is not a pattern module
   47	ID: PMNFR5 - Category: Inputs - Parameter/Variable Naming		NA if this is not a pattern module
   48	ID: TFFR1 - Category: Composition - Cross-Referencing Modules
   49	ID: TFFR2 - Category: Outputs - Additional Terraform Outputs	Yes	Yes if linting / terraform check passed
   50	ID: TFNFR1 - Category: Documentation - Descriptions
   51	ID: TFNFR2 - Category: Documentation - Module Documentation Generation	Yes	Yes if linting / docs check passed
   52	ID: TFNFR3 - Category: Contribution/Support - GitHub Repo Branch Protection	Yes	Yes if AVM Template Repo has been used
   53	ID: TFNFR4 - Category: Composition - Code Styling - lower snake_casing	Yes	Yes if linting / terraform check passed
   54	ID: TFNFR5 - Category: Testing - Test Tooling	Yes	Yes if linting / terraform check passed
   55	ID: TFNFR6 - Category: Code Style - Resource & Data Order
   56	ID: TFNFR7 - Category: Code Style - count & for_each Use
   57	ID: TFNFR8 - Category: Code Style - Resource & Data Block Orders	Yes	Yes if linting / avmfix check passed
   58	ID: TFNFR9 - Category: Code Style - Module Block Order
   59	ID: TFNFR10 - Category: Code Style - No Double Quotes in ignore_changes
   60	ID: TFNFR11 - Category: Code Style - Null Comparison Toggle
   61	ID: TFNFR12 - Category: Code Style - Dynamic for Optional Nested Objects
   62	ID: TFNFR13 - Category: Code Style - Default Values with coalesce/try
   63	ID: TFNFR14 - Category: Inputs - Not allowed variables
   64	ID: TFNFR15 - Category: Code Style - Variable Definition Order	Yes	Yes if linting / avmfix check passed
   65	ID: TFNFR16 - Category: Code Style - Variable Naming Rules	Yes	Yes if linting / terraform check passed
   66	ID: TFNFR17 - Category: Code Style - Variables with Descriptions	Yes	Yes if linting / terraform check passed
   67	ID: TFNFR18 - Category: Code Style - Variables with Types	Yes	Yes if linting / terraform check passed
   68	ID: TFNFR19 - Category: Code Style - Sensitive Data Variables
   69	ID: TFNFR20 - Category: Code Style - Non-Nullable Defaults for collection values
   70	ID: TFNFR21 - Category: Code Style - Discourage Nullability by Default	Yes	Yes if linting / avmfix check passed
   71	ID: TFNFR22 - Category: Code Style - Avoid sensitive = false	Yes	Yes if linting / avmfix check passed
   72	ID: TFNFR23 - Category: Code Style - Sensitive Default Value Conditions	Yes	Yes if linting / terraform check passed
   73	ID: TFNFR24 - Category: Code Style - Handling Deprecated Variables	NA	Module Owner to action this spec post-publish as appropriate
   74	ID: TFNFR25 - Category: Code Style - Verified Modules Requirements	Yes	Yes if linting / terraform check passed
   75	ID: TFNFR26 - Category: Code Style - Providers in required_providers	Yes	Yes if linting / terraform check passed
   76	ID: TFNFR27 - Category: Code Style - Provider Declarations in Modules	Yes	Yes if linting / terraform check passed
   77	ID: TFNFR29 - Category: Code Style - Sensitive Data Outputs	Yes	Yes if linting / avmfix check passed
   78	ID: TFNFR30 - Category: Code Style - Handling Deprecated Outputs	NA	Module Owner to action this spec post-publish as appropriate
   79	ID: TFNFR31 - Category: Code Style - locals.tf for Locals Only
   80	ID: TFNFR32 - Category: Code Style - Alphabetical Local Arrangement	Yes	Yes if linting / avmfix check passed
   81	ID: TFNFR33 - Category: Code Style - Precise Local Types
   82	ID: TFNFR34 - Category: Code Style - Using Feature Toggles	NA	Module Owner to action this spec post-publish as appropriate
   83	ID: TFNFR35 - Category: Code Style - Reviewing Potential Breaking Changes	NA	Module Owner to action this spec post-publish as appropriate
   84	ID: TFNFR36 - Category: Code Style - Setting prevent_deletion_if_contains_resources
   85	ID: TFNFR37 - Category: Code Style - Tool Usage by Module Owner

7. The module reviewer can update the Compliance column for specs in line 42 to 47 to NA, in case the module being reviewed isn’t a pattern module.

8. The module reviewer reviews the code in the PR and leaves comments to request any necessary updates.

9. The module reviewer assigns the AVM-Review issue to the module owner and links the AVM-Review Issue to the AVM-Review-PR so that once the module reviewer approves the PR and the module owner merges the AVM-Review-PR, the AMV-Review issue is automatically closed. The module reviews responds to the module owner’s comment on the Module Proposal in AVM Repo with the following

   ➕ AVM Terraform Module Review Initiation Message

   Thank you for requesting a review of your module. The AVM module review process has been initiated, please perform the **Requested Actions** on the AVM-Review issue on the module repo.

10. The module owner updates the check list and the table in the AVM-Review issue and notifies the module reviewer in a comment.

11. The module reviewer performs the final review and ensures that all checks in the checklist are complete and the specifications table has been updated with no requirements having compliance as ‘No’.

12. The module reviewer approves the AVM-Review-PR, and leaves the following comment on the AVM-Review issue with the following comment.

    ➕ AVM Terraform Module Review Completion Message

    Thank you for contributing this module and completing the review process per AVM specs. The AVM-Review-PR has been approved and once you merge it that will close this AVM-Review issue. Please create a release with an initial minor version of `v0.1.0` (tags **MUST** include the `v` prefix) and then contact the AVM core team to publish this module to the HashiCorp Terraform Registry via HCP Terraform. Please continue publishing future versions in the v0.x.y minor range (e.g., `v0.1.0`, `v0.1.1`, `v0.2.0`, etc.) until the AVM team notifies you that publishing `v1.0.0` is allowed.
    
    **Requested Action**: Once the AVM core team has published the module, please update your [module proposal](REPLACE WITH THE LINK TO THE MODULE PROPOSAL) with the following comment.
    
    "The initial review of this module is complete, and the module has been published to the registry by the AVM core team. Requesting AVM team to close this module proposal and mark the module available in the module index.
    Terraform Registry Link: <REPLACE WITH THE LINK OF THE MODULE IN TERRAFORM REGISTRY>
    GitHub Repo Link: <REPLACE WITH THE LINK OF THE MODULE IN GITHUB>"

13. Once the module owner perform the requested action in the previous step, the module reviewer updates the module proposal by performing the following steps:

• Assign label Status: Module Available :green_circle: to the module proposal.
• Update the module index excel file and CSV file by creating a PR to update the module index and links the module proposal as an issue that gets closed once the PR is merged which will move the module proposal from “In Review” to “Done” in the AVM - Module Triage project.

Advanced Topics & FAQ

This page covers advanced scenarios and frequently asked questions that go beyond the standard contribution flow.

Offline and air-gapped module mirroring

The offline sync utility mirrors AVM Terraform modules and rewrites registry dependencies as git references for offline or air-gapped environments.

Using a custom Azure test subscription

By default, CI end-to-end tests run against a centrally managed Azure subscription. If your module requires a different environment (e.g. due to quota limits or tenant-level deployments), you can override the defaults.

1. Create a user-assigned managed identity in your target Azure environment.
2. Create GitHub federated credentials for the managed identity, using the module’s GitHub organization and repository. Select entity type environment and set the name to test.
3. Assign appropriate roles to the managed identity.
4. Elevate your access via the Open Source Portal.
5. Go to the repository Settings > Environments > test and add the following secrets:
   • ARM_CLIENT_ID_OVERRIDE — Client ID of the managed identity.
   • ARM_TENANT_ID_OVERRIDE — Tenant ID.
   • ARM_SUBSCRIPTION_ID_OVERRIDE — Subscription ID.

Custom variables and secrets for end-to-end tests

The test environment in each module repository has approvals and secrets configured for e2e tests. If you need additional variables or secrets:

• Add them to the test environment in your repository settings.
• They must be prefixed with TF_VAR_ — other prefixes will be ignored.

OPA (Conftest) policy exceptions

Conftest checks the plan for compliance with the Well-Architected Framework using OPA policies.

If you get policy failures that need an exception, create a .rego file in the exceptions sub-directory of the relevant example:

package Azure_Proactive_Resiliency_Library_v2
import rego.v1
exception contains rules if {
  rules = ["configure_aks_default_node_pool_zones"]
}

TFLint rule overrides

TFLint checks AVM spec compliance using the AVM custom ruleset.

To override a rule, create one of the following HCL files in the root of your module:

Example:

# Disable the required resource id output rule — this is a pattern module.
rule "required_output_rmfr7" {
  enabled = false
}

Include a comment explaining why the rule is disabled.

Excluding examples from end-to-end testing

Create a file called .e2eignore in the example directory. Its contents should explain why the example is excluded from tests.

Global test setup and teardown

Avm.Authoring has no global setup or teardown hook. It does not execute or reject the legacy files:

• examples/setup.sh
• examples/teardown.sh

Move required setup and cleanup into idempotent per-example pre.ps1 and post.ps1 hooks. Coordinate removal of legacy global scripts with the repository’s centrally managed CI workflow migration because older workflows can still invoke them.

Per-example pre and post scripts

For example-specific setup/teardown:

• examples/<example_name>/pre.ps1 (optional) — runs before Terraform commands for the example.
• examples/<example_name>/post.ps1 (optional) — always runs after the example, including after a pre-hook or initialization failure.

Shell equivalents are rejected. Each PowerShell hook runs in an isolated process; see Lifecycle hooks for .env, path, and error-handling guidance.

Repository synchronization PRs

Repository sync regularly compares each module repository with the shared managed files and opens a PR when updates are available. These PRs are normally merged automatically. Module owners will be informed about one-off PRs that require intervention.

These PRs do not change module code, so no new release is needed.

Eventual consistency

The Azure Resource Manager API can be eventually consistent. For example, data plane role assignments may not be available immediately after creation.

Use the AzAPI provider’s retry functionality to handle eventual consistency instead of arbitrary time_sleep delays. The AzAPI provider supports configurable retry with retry blocks that can match on specific error codes, providing a more reliable and efficient approach.

Repository Creation Process

1. Add yourself to the Module Owners Team and Open Source orgs

If you have already completed these steps, skip to step 2.

1. Open the Open Source Portal and ensure your GitHub account is linked to your Microsoft account.
2. Open the Open Source Portal and ensure you are a member of the Azure and Microsoft organizations.
3. Request access via the Azure Verified Modules (AVM) Module Contributors access package. Approval adds you to the azure-verified-modules-module-contributors Entra group.

2. Gather repository information

You’ll need the following from the module request issue:

3. Create the repository

Prerequisites:

• PowerShell 7.4 or later
• Git
• GitHub CLI

Clone and prepare

Use the repository creation tooling:

cd ~
git clone "https://github.com/Azure/azure-verified-modules-tools"
cd ./azure-verified-modules-tools/repository-management/repository-creation

Authenticate

gh auth login -h "github.com" -w -p "https"

Run the creation script

if(!(Test-Path -Path "./scripts/New-Repository.ps1")) {
    Write-Error "This script must be run from the repository-creation directory."
    exit 1
}

# Required Inputs
$moduleName = "<module name>" # e.g. avm-res-network-virtualnetwork
$moduleDisplayName = "<module description>"
$resourceProviderNamespace = "" # Leave empty for Pattern/Utility modules
$resourceType = "" # Leave empty for Pattern/Utility modules
$ownerPrimaryGitHubHandle = "<github handle>"
$ownerPrimaryDisplayName = "<display name>"

# Optional
$moduleAlternativeNames = ""
$ownerSecondaryGitHubHandle = ""
$ownerSecondaryDisplayName = ""

./scripts/New-Repository.ps1 `
    -moduleName $moduleName `
    -moduleDisplayName $moduleDisplayName `
    -resourceProviderNamespace $resourceProviderNamespace `
    -resourceType $resourceType `
    -ownerPrimaryGitHubHandle $ownerPrimaryGitHubHandle `
    -ownerPrimaryDisplayName $ownerPrimaryDisplayName `
    -moduleAlternativeNames $moduleAlternativeNames `
    -ownerSecondaryGitHubHandle $ownerSecondaryGitHubHandle `
    -ownerSecondaryDisplayName $ownerSecondaryDisplayName

Complete Open Source Portal Setup

The script will pause and prompt you to configure the Open Source Portal. Follow the link in the script output.

Return to the terminal and type yes to complete repository configuration.

The script will automatically:

• Create a PR to add module metadata to the repository-sync configuration.
• Create a PR to install the Azure Verified Modules GitHub App.

4. Upgrade just-in-time access to JITv2

New repositories default to JIT v1. AVM repositories must be upgraded to JIT v2 and tied to the shared service-AVM-azure-verified-modules-module-owners rule, so that just-in-time elevation is governed centrally by the AVM team rather than by a repository-specific rule.

This is a one-off manual action in the Open Source Portal. You need Direct Owner access to the repository (configured in the previous step) to complete it.

Migrate the repository to JIT v2

1. Open the repository overview on the Open Source Portal: https://repos.opensource.microsoft.com/orgs/Azure/repos/<module name>.
2. In the right-hand sidebar, find the Improved Just-in-time (New) panel and click Next.
3. Review the concepts (Rule Version, Rule, Tie) and click Next.
4. Leave Require approval for elevation selected and click Upgrade <module name> now.

This migrates the repository to JIT v2 and creates a temporary repository-scoped starter rule. Reload the page and confirm the Just-in-time elevation section now shows JIT version: JIT v2.

Tie the repository to the shared AVM rule

1. On the repository overview, click Advanced JIT options, then select Propose a new tie.
2. Under Propose tying a new rule to this repository, enter the Rule ID service-AVM-azure-verified-modules-module-owners and click Review.
3. Confirm the details and click Create tie.

The tie is created in a pending approval state, so the temporary repository-scoped rule stays active until the tie is approved.

Remove yourself as a Direct Owner

You were added as a Direct Owner so you could perform the JIT configuration above. Once you have finished both the JIT v2 upgrade and the shared-rule tie, remove your own account so that only jaredholgate and jatracey remain as Direct Owners.

1. On the Open Source Portal, open the repository’s Compliance tab.
2. Under Direct owners, remove your own account, leaving only jaredholgate and jatracey.

5. Wait for the GitHub App and repository sync

After the app is installed, repository sync applies the shared repository configuration and managed files to complete the setup.