avm-tf-process

name	avm-tf-process
description	Use for the AVM Terraform contribution process from module proposal and repository setup through implementation, Avm.Authoring validation, pull request review, and release.

AVM Terraform Contribution Process

Use the current AVM process and specification pages from https://azure.github.io/Azure-Verified-Modules/llms.txt. Older public setup pages or module repositories may still contain the retired launcher, Makefile, container, or Porch flow.

1. Confirm classification and ownership

Determine whether the work is a resource, pattern, or utility module. Confirm the approved module name and ownership from the AVM indexes and proposal rather than inventing a name.

Before creating or restructuring a repository, read the current requirements for:

• repository naming and visibility;
• owner and AVM team permissions;
• CODEOWNERS;
• branch protection and required checks;
• issue and pull request templates;
• release and publishing; and
• support lifecycle.

2. Establish the managed repository baseline

Start from the current AVM Terraform template or governance-managed repository state. Import Avm.Authoring and synchronize managed files:

Install-PSResource -Name Avm.Authoring -Repository PSGallery -TrustRepository
Import-Module Avm.Authoring
avm version
avm sync

Review synchronized changes before continuing. Do not restore files from the retired Make, Porch, or container workflow.

3. Implement from current specifications

Build every new resource-deploying module repository on AzAPI. Do not declare or configure hashicorp/azurerm, and do not create any azurerm_* resource or data source for control-plane operations, convenience, or ordinary supporting infrastructure in implementation, submodules, examples, E2E configurations, Terraform tests, fixtures, setup or teardown Terraform, migration examples, documentation examples, or generated snippets.

When supporting configuration needs a direct Azure resource that the module under test does not supply, use an AzAPI resource, data source, or action. Each standalone Terraform root that performs direct Azure operations includes Azure/azapi in required_providers.

Permit hashicorp/azurerm ~> 4.0 only when required by an independently justified azurerm_* resource or data-source block. Each block scopes to one specific unsupported data-plane/non-ARM operation, adds the prescribed provider_azurerm_disallowed TFLint exclusion, documents the exact block and why AzAPI cannot implement it with an upstream AzAPI issue or pull request, and is replaced when support ships. One valid block does not authorize another. Examples and tests may configure AzureRM only to exercise such blocks.

Fetch llms.txt, then read each applicable raw spec page. At minimum, review:

• module classification and composition rules;
• TFFR3-TFFR8 for AzAPI;
• TFRMFR1 and TFNFR38 for parent and resource IDs;
• TFRMNFR1 and TFRMNFR2 for submodules and resource labels;
• TFNFR39 for file layout;
• standard interfaces and telemetry;
• tests and examples;
• documentation; and
• semantic versioning and breaking changes.

Use the local specialized skills for implementation details, but resolve any conflict in favor of the current published spec.

4. Develop on a focused branch

Keep changes scoped and preserve unrelated history. Add or update:

• Terraform implementation and exact types;
• root and submodule tests;
• representative examples;
• _header.md and _footer.md;
• migration or upgrade-path coverage when state or addresses change; and
• generated README files through Avm.Authoring.

Scripts and lifecycle hooks must be PowerShell. Supported hook names include:

• tests/unit/setup.ps1;
• tests/integration/setup.ps1;
• examples/<name>/pre.ps1;
• examples/<name>/post.ps1; and
• examples/<name>/tflint-pre.ps1.

Do not add shell-hook counterparts.

5. Run targeted tests

Choose the smallest tier that proves the change:

avm test unit
avm test integration
avm test e2e --example <example-name>

Unit tests mock all required providers. Integration and E2E tests need real Azure authentication. E2E tests must prove deployment, idempotency, and cleanup.

6. Apply pre-commit changes

Run:

avm pre-commit

For Terraform this performs managed-file sync, fixable convention rules, transforms, formatting, and documentation generation. Review every generated or synchronized change and rerun targeted tests if the generated change affects behavior.

7. Commit, then run the full PR gate

Commit the complete worktree before running:

avm pr-check

avm pr-check requires a clean Git worktree. It checks sync, formatting, transforms, lint, APRL/AVMSEC policy evaluation, conventions, Terraform validation, and documentation. Unit tests remain a separate test tier and CI job; a passing PR check is not a substitute for required unit, integration, or E2E coverage.

8. Open and review the pull request

The pull request must explain:

• what changed and why;
• applicable specification IDs;
• compatibility or breaking-change impact;
• state migration steps when addresses or providers changed;
• tests and examples exercised; and
• confirmation that control-plane and supporting resources use AzAPI, plus the evidence and upstream link for any narrow data-plane/non-ARM AzureRM exception.

Review the final diff rather than only the hand-authored files. Managed and generated outputs are part of the change.

9. Release

Follow the current AVM semantic-versioning and publishing process. Confirm:

• the change classification matches the release version;
• generated documentation is current;
• required checks and test tiers passed;
• upgrade notes are included where needed; and
• repository permissions and release automation remain governance-compliant.

Use Avm.Authoring throughout. Do not substitute ./avm, avm.ps1, Make, Porch, Docker, Podman, or manually installed pinned tools.