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 template repo here.

• tests/ - (for unit tests and additional tests if required - e.g. tflint etc.)
  • unit/ - (optional, may use further sub-directories if required)
• modules/ - (for sub-modules only if used)
• examples/ - (all examples must deploy without 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)
  • <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

Directory and File Structure

/ root
│
├───.github/
│   ├───actions/
│   │   ├───avmfix/
│   │   │   └───action.yml
│   │   ├───docs-check/
│   │   │   └───action.yml
│   │   ├───e2e-getexamples/
│   │   │   └───action.yml
│   │   ├───e2e-testexamples/
│   │   │   └───action.yml
│   │   ├───linting/
│   │   │   └───action.yml
│   │   └───version-check/
│   │       └───action.yml
│   ├───policies/
│   │   ├───avmrequiredfiles.yml
│   │   └───branchprotection.yml
│   ├───workflows/
│   │   ├───e2e.yml
│   │   ├───linting.yml
│   │   └───version-check.yml
│   ├───CODEOWNERS
│   └───dependabot.yml
├───.vscode/
│   ├───extensions.json
│   └───settings.json
├───examples/
│   ├───<example_folder>/
│   │   ├───README.md
│   │   ├───_footer.md
│   │   ├───_header.md
│   │   ├───main.tf
│   │   └───variables.tf
│   ├───.terraform-docs.yml
│   └───README.md
├───modules/
│   └───README.md
├───tests/
│   └───README.md
├───.gitignore
├───.terraform-docs.yml
├───CODE_OF_CONDUCT.md
├───LICENSE
├───Makefile
├───README.md
├───SECURITY.md
├───SUPPORT.md
├───_footer.md
├───_header.md
├───avm
├───avm.bat
├───locals.tf
├───main.privateendpoint.tf
├───main.telemetry.tf
├───main.tf
├───outputs.tf
├───terraform.tf
└───variables.tf

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.

Telemetry

To meet SFR3 & SFR4.
We use a telemetry provider modtm.
This is a lightweight telemetry provider that sends telemetry data to Azure Application Insights via a HTTP POST front end service.

The telemetry provider is included in the module by default and is enabled by default.
You do not need to change the configuration included in the template repo.

You must make sure to have the modtm provider in your required_providers.
The linter will check this for you.
However, inside your terraform.tf file please make sure you have this entry:

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

Eventual Consistency

When creating modules, it is important to understand that the Azure Resource Manager (ARM) API is sometimes eventually consistent.
This means that when you create a resource, it may not be available immediately.
A good example of this is data plane role assignments.
When you create such a role assignment, it may take some time for the role assignment to be available.
We can use an optional time_sleep resource to wait for the role assignment to be available before creating resources that depend on it.

# In variables.tf...
variable "wait_for_rbac_before_foo_operations" {
  type: object({
    create  = optional(string, "30s")
    destroy = optional(string, "0s")
  })
  default     = {}
  description = <<DESCRIPTION
This variable controls the amount of time to wait before performing foo operations.
It only applies when `var.role_assignments` and `var.foo` are both set.
This is useful when you are creating role assignments on the bar resource and immediately creating foo resources in it.
The default is 30 seconds for create and 0 seconds for destroy.
DESCRIPTION
}

# In main.tf...
resource "time_sleep" "wait_for_rbac_before_foo_operations" {
  count = length(var.role_assignments) > 0 && length(var.foo) > 0 ? 1 : 0
  depends_on = [
    azurerm_role_assignment.this
  ]
  create_duration  = var.wait_for_rbac_before_foo_operations.create
  destroy_duration = var.wait_for_rbac_before_foo_operations.destroy

  # This ensures that the sleep is re-created when the role assignments change.
  triggers = {
    role_assignments = jsonencode(var.role_assignments)
  }
}

resource "azurerm_foo" "this" {
  for_each = var.foo
  depends_on = [
    time_sleep.wait_for_rbac_before_foo_operations
  ]
  # ...
}

Terraform Contribution Flow

High-level contribution flow

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

flowchart TD
  A(1 - Fork the module source repository)
    click A "/Azure-Verified-Modules/contributing/terraform/terraform-contribution-flow/#1-fork-the-module-source-repository"
  B(2 - Setup your Azure test environment)
    click B "/Azure-Verified-Modules/contributing/terraform/terraform-contribution-flow/#2-prepare-your-azure-test-environment"
  C(3 - Implement your contribution)
    click C "/Azure-Verified-Modules/contributing/terraform/terraform-contribution-flow/#3-implement-your-contribution"
  D{4 - Pre-commit<br>checks successful?}
    click D "/Azure-Verified-Modules/contributing/terraform/terraform-contribution-flow/#4-run-pre-commit-checks"
  E(5 - Create a pull request to the upstream repository)
    click E "/Azure-Verified-Modules/contributing/terraform/terraform-contribution-flow/#5-create-a-pull-request-to-the-upstream-repository"
  A --> B
  B --> C
  C --> D
  D -->|yes|E
  D -->|no|C

GitFlow for contributors

The GitFlow process outlined here depicts and suggests a way of working with Git and GitHub. It serves to synchronize the forked repository with the original upstream repository. It is not a strict requirement to follow this process, but it is highly recommended to do so.

---

config:
  logLevel: debug
  gitGraph:
    rotateCommitLabel: false
---

gitGraph LR:
  commit id:"fork"
  branch fork/main
  checkout fork/main
  commit id:"checkout feature" type: HIGHLIGHT
  branch feature
  checkout feature
  commit id:"checkout fix"
  branch fix
  checkout main
  merge feature id: "Pull Request 'Feature'" type: HIGHLIGHT
  checkout fix
  commit id:"Patch 1"
  commit id:"Patch 2"
  checkout main
  merge fix id: "Pull Request 'Fix'" type: HIGHLIGHT

Prepare your developer environment

1. Fork the module source repository

Module contributors are expected to fork the corresponding repository and work on a branch from within their fork, before then creating a Pull Request (PR) back into the source repository’s main branch.

To do so, simply navigate to your desired repository, select the 'Fork' button to the top right of the UI, select where the fork should be created (i.e., the owning organization) and finally click ‘Create fork’.

2. Prepare your Azure test environment

AVM performs end-to-end (e2e) test deployments of all modules in Azure for validation. We recommend you to perform a local e2e test deployment of your module before you create a PR to the upstream repository. Especially because the e2e test deployment will be triggered automatically once you create a PR to the upstream repository.

1. Have/create an Azure Active Directory Service Principal with at least Contributor & User Access Administrator permissions on the Management-Group/Subscription you want to test the modules in. You might find the following links useful:

   • Create a service principal (Azure CLI) - Recommended
   • Create a service principal (Azure Portal)
   • Create a service principal (PowerShell)
   • Find Service Principal object ID
   • Find managed Identity Service Principal
   • Note down the following pieces of information
   • Application (Client) ID
   • Service Principal Secret (password)
   • Optional: Tenant ID
   • Optional: Subscription ID

   # Linux/MacOs
   export ARM_SUBSCRIPTION_ID=$(az account show --query id --output tsv) # or set <subscription_id>
   export ARM_TENANT_ID=$(az account show --query tenantId --output tsv) # or set <tenant_id>
   export ARM_CLIENT_ID=<client_id>
   export ARM_CLIENT_SECRET=<service_principal_password>
   
   # Windows/Powershell
   $env:ARM_SUBSCRIPTION_ID = $(az account show --query id --output tsv) # or set <subscription_id>
   $env:ARM_TENANT_ID = $(az account show --query tenantId --output tsv) # or set <tenant_id>
   $env:ARM_CLIENT_ID = "<client_id>"
   $env:ARM_CLIENT_SECRET = "<service_principal_password>"

2. Change to the root of your module repository and run ./avm docscheck (Linux/MacOs) / avm.bat docscheck (Windows) to verify the container image is working as expected or needs to be pulled first. You will need this later.

   

3. Implement your contribution

To implement your contribution, we kindly ask you to first review the Terraform specifications and composition guidelines in particular to make sure your contribution complies with the repository’s design and principles.

4. Run Pre-commit Checks

4.1. Run pre-commit and pr-check

The following commands will run all pre-commit checks and the pr-check.

# Running all pre-commit checks
# `pre-commit` runs depsensure fmt fumpt autofix docs
# `pr-check` runs fmtcheck tfvalidatecheck lint unit-test

## Linux/MacOs
./avm pre-commit
./avm pr-check

## Windows
avm.bat pre-commit
avm.bat pr-check

4.2 Run e2e tests

Currently you have two options to run e2e tests:

1. Run e2e tests with the help of the azterraform docker container image.

   # Linux/MacOs
   
   docker run --rm -v $(pwd):/src -w /src -v $HOME/.azure:/root/.azure -e TF_IN_AUTOMATION -e AVM_MOD_PATH=/src -e AVM_EXAMPLE=<example_folder> -e ARM_SUBSCRIPTION_ID -e ARM_TENANT_ID -e ARM_CLIENT_ID -e ARM_CLIENT_SECRET mcr.microsoft.com/azterraform:latest make test-example
   
   # Powershell
   
   docker run --rm -v ${pwd}:/src -w /src -v $HOME/.azure:/root/.azure -e TF_IN_AUTOMATION -e AVM_MOD_PATH=/src -e AVM_EXAMPLE=<example_folder> -e ARM_SUBSCRIPTION_ID -e ARM_TENANT_ID -e ARM_CLIENT_ID -e ARM_CLIENT_SECRET mcr.microsoft.com/azterraform:latest make test-example

   Make sure to replace <client_id> and <service_principal_password> with the values of your service principal as well as <example_folder> (e.g. default) with the name of the example folder you want to run e2e tests for.

2. Run e2e tests with the help of terraform init/plan/apply.

   Simply run terraform init and terraform apply in the example folder you want to run e2e tests for. Make sure to set the environment variables ARM_SUBSCRIPTION_ID, ARM_TENANT_ID, ARM_CLIENT_ID and ARM_CLIENT_SECRET before you run terraform init and terraform apply or make sure you have a valid Azure CLI session and are logged in with az login.

5. Create a pull request to the upstream repository

Once you are satisfied with your contribution and validated it, submit a pull request to the upstream repository and work with the module owner to get the module reviewed by the AVM Core team, by following the initial module review process for Terraform Modules, described here. This is a prerequisite for publishing the module. Once the review process is complete and your PR is approved, merge it into the upstream repository and the Module owner will publish the module to the HashiCorp Terraform Registry.

5.1 Create the Pull Request [Contributor]

These steps are performed by the contributor:

1. Navigate to the upstream repository and click on the Pull requests tab.
2. Click on the New pull request button.
3. Ensure the base repository is set to the upstream AVM repo.
4. Ensure the base branch is set to main.
5. Ensure your head repository and compare branch are set to your fork and the branch you are working on.
6. Click on the Create pull request button.

5.2 Review the Pull Request [Owner]

1. IMPORTANT: The module owner must first check for any malicious code or changes to workflow files. If they are found, the owner should close the PR and report the contributor.
2. Review the changes made by the contributor and determine whether end to end tests need to be run.
3. If end to end tests do not need to be run (e.g. doc changes, small changes, etc) then so long as the static analysis passes, the PR can be merged to main.
4. If end to end tests do need to be run, then follow the steps in 5.3.

5.3 Release Branch and Run End to End Tests [Owner]

1. IMPORTANT: The module owner must first check for any malicious code or changes to workflow files. If they are found, the owner should close the PR and report the contributor.
2. Create a release branch from main. Suggested naminmg convention is release/<description-of-change>.
3. Open the PR created by the contributor and click Edit at the top right of the PR.
4. Change the base branch to the release branch you just created.
5. Wait for the PR checks to run, validate the code looks good and then merge the PR into the release branch.
6. Create a new PR from the release branch to the main branch of the AVM module.
7. The end to end tests should trigger and you can approve the run.
8. Once the end to end tests have passed, merge the PR into the main branch.
9. If the end to end tests fail, investigate the failure. You have two options:
   1. Work with the contributor to resolve the issue and ask them to submit a new PR from their fork branch to the release branch.
      1. Re-run the tests and merge to main. Repeat the loop as required.
   2. If the issue is a simple fix, resolve it directly in the release branch, re-run the tests and merge to main.

Common mistakes to avoid and recommendations to follow

• If you contribute to a new module then search and update TODOs (which are coming with the terraform-azurerm-avm-template) within the code and remove the TODO comments once complete
• terraform.lock.hcl shouldn’t be in the repository as per the .gitignore file
• Update the support.md file
• \_header.md needs to be updated
• support.md needs to be updated
• Exclude terraform.tfvars file from the repository

Terraform Contribution Prerequisites

GitHub Account Link and Access

To contribute to this project, you need to have a GitHub account which is linked to your Microsoft corporate identity account and be a member of the Azure organization.

Tooling

Required Tooling

To contribute to this project the following tooling is required:

• Git

  If just installed, don’t forget to set both your git username & password

  git config --global user.name "John Doe"
  git config --global user.email "johndoe@example.com"

• Terraform

• Azure CLI

• Visual Studio Code

  • Terraform extension for Visual Studio Code
  • EditorConfig for VS Code

• Docker

  • Azure Verified Terraform Scaffold (mcr.microsoft.com/azterraform:latest)

Recommended Tooling

The following tooling/extensions are recommended to assist you developing for the project:

• Go (for writing tests)
• tfenv - useful when working on multiple modules that use different Terraform versions from the same machine

Visual Studio Code Extensions

• Go extension for Visual Studio Code
• For visibility of Bracket Pairs:
  • Inside Visual Studio Code, add editor.bracketPairColorization.enabled: true to your settings.json, to enable bracket pair colorization.

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 avm-core-team-technical-terraform 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 grept and pre-commit and pr-check.
   • 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. You may proceed with [publishing](/Azure-Verified-Modules/contributing/terraform/terraform-contribution-flow/owner-contribution-flow/#7-publish-the-module) this module to the HashiCorp Terraform Registry with an initial pre-release version of v0.1.0. Please keep future versions also pre-release i.e. < 1.0.0 until AVM becomes generally available (GA) of which the AVM team will notify you.
    
    **Requested Action**: Once published 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. 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.

Terraform Module Testing

When you author your Azure Verified Module (AVM) Terraform module, you should ensure that it is well tested.
This document outlines the testing framework and tools that are used to test AVM Terraform modules.

Testing Framework Composition

For Terraform modules, we use the following tools:

Mandatory tooling:

• avmfix for advanced formatting
• Conftest, and Open Policy Agent (OPA) for well architected compliance
• grept (Go REPository linTer) for repository contents
• terraform-docs for documentation generation
• TFLint for spec compliance

Optional tooling:

• terraform test for unit testing

Before Submitting a Pull Request

Before you submit a pull request to your module, you should ensure that the following checks are passed.
You can run the linting tools locally by running the following command:

Prerequisites

You need to have the following tools installed:

• A container runtime - you can use Docker Desktop or Podman

Linux / MacOS / WSL

./avm pre-commit
./avm pr-check

Windows

.\avm.bat pre-commit
.\avm.bat pr-check

Doing so will shorten the development cycle and ensure that your module is compliant with the AVM specifications.

GitHub Actions and Pull Requests

We centrally manage the test workflows for your Terraform modules.
We also provide a test environment (Azure Subscription) as part of the testing framework.

Linting

The linting.yml workflow in your repo (.github/workflows/linting.yml) is responsible for static analysis of your module.
It will run the following centralized tests:

• avmfix to ensure that your module is formatted correctly.
• terraform-docs to ensure that your module documentation is up to date.
• TFLint to ensure that your module is compliant with the AVM specifications.

End-to-end testing

The e2e.yml workflow in your repo (.github/workflows/e2e.yml) is responsible for end-to-end testing of your module examples.
It will run the following centralized test workflow: https://github.com/Azure/terraform-azurerm-avm-template/blob/main/.github/workflows/test-examples-template.yml.

It will run the following tasks:

• List all the module examples in the examples directory.
• Conftest will check the plan for compliance with the well-architected framework using OPA.
• Your example will be tested for idempotency by running terraform apply and then terraform plan again.
• Your example will be destroyed by running terraform destroy.

Currently it is not possible to run the end-to-end tests locally, however you can run terraform apply and terraform destroy commands locally to test your module examples.

OPA (Open Policy Agent) & Conftest

Conftest is the first step in the AVM end-to-end testing framework.
It will check the plan for compliance with the well-architected framework using OPA.
The policies that we use are available here: https://github.com/Azure/policy-library-avm.

If you get failures, you should examine them to understand how you can make your example compliant with the well-architected framework.

Creating exceptions

In some circumstances, you may need to create an exception for a policy, you can do so by creating a .rego file in the exceptions sub-directory of your example.
For example, to exclude the rule called "configure_aks_default_node_pool_zones", create a file called exceptions/exception.rego in your example, with the following content:

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

TFLint

TFLint is used to check that your module is compliant with the AVM specifications.
We use a custom ruleset for TFLint to check for AVM compliance: https://github.com/Azure/tflint-ruleset-avm.

Excluding rules

If you need to exclude a rule from TFLint, you can do so by creating one of the following in the root of your module:

• avm.tflint.override.hcl - to override the rules for the root module
• avm.tflint.override_module.hcl - to override the rules for submodules
• avm.tflint.override_example.hcl - to override the rules for examples

These files are HCL files that contain the rules that you want to override.
Here is some example syntax:

# Disable the required resource id output rule as this is a pattern module and it does not make sense here.
rule "required_output_rmfr7" {
  enabled = false
}

Please include a comment in the file explaining why you are disabling the rule.

Excluding examples from end-to-end testing

If you have examples that you do not want to be tested, you can exclude them by creating a file called .e2eignore in the example directory.
The contents of the file should explain why the example is excluded from testing.

Global test setup and teardown

Some modules require a global setup and teardown to be run before and after ALL examples.
We provide a way to do this by creating a file called examples/setup.sh in the root of your module.
This script will be run before all examples are tested, and will be authorized with the same credentials as the examples.

You can optionally supply a teardown script that will be run after all examples are tested.
This should be called examples/teardown.sh.

Pre and post scripts per-example

Some examples require pre and post commands that are specific to that example.
Use cases here can be to modify the example files to ensure unique names or to run some commands before or after the example is tested.

You can do this by creating a file called examples/example_name/pre.sh in the example directory.
This script will be run before the example is tested, and will be authorized with the same credentials as the example.
You can optionally supply a post script that will be run after the example is tested.
This should be called examples/example_name/post.sh.

The pre and post scripts are run in the context of the example directory, so you can use relative paths to access files.

Grept and the chore: repository governance pull requests

We run a weekly workflow that checks the contents of your module and creates a pull request if it finds any issues.
If you see a pull request with the title chore: repository governance, it means that the workflow has found some issues with your module, so please check the pull request and merge it to ensure you are compliant.

You do not need to release a new version of your module when you merge these pull requests, as they do not change the module code.

Overriding the default test subscription (using a different Azure environment)

If your module deploys resource that are not compatible with the default test subscription, you can override these defaults by setting additional environment secrets in your GitHub repository.

You might need to do this if:

• The resources you are deploying are constrained by quota or subscription limits.
• You need to deploy resources at scopes higher than subscription level (e.g. management group or tenant).

To override the Azure environment, you can specify the environment in your module’s configuration or set the following environment variables in your GitHub repository settings:

1. Create a user-assigned managed identity in the Azure environment you want to use.
2. Create GitHub federated credentials for the user-assigned managed identity in the Azure environment you want to use, using the github organization and repository of your module. Select entity type ’environment’ and add test for the name.
3. Create appropriate role assignments for the user-assigned managed identity in the Azure environment you want to use.
4. Now, elevate you access to administrator by going to the open source portal: https://repos.opensource.microsoft.com/orgs/Azure/repos/REPOSITORY-NAME/jit.
5. Then, go to the settings of your GitHub repository and select environments.
6. Select the test environment.
7. Add the following secrets:
   • ARM_CLIENT_ID_OVERRIDE - The client ID of the user-assigned managed identity.
   • ARM_TENANT_ID_OVERRIDE - The tenant ID of the user-assigned managed identity.
   • ARM_SUBSCRIPTION_ID_OVERRIDE - The subscription ID you want to use for the tests.

Terraform Test (Optional)

Authors may choose to use terraform test to run unit and integration tests on their modules.

 Unit tests

Test files should be placed in the tests/unit directory.
They can be run using the following command:

./avm unit-test

Authors SHOULD use unit tests with mocked providers.
This ensures that the tests are fast and do not require any external dependencies.

Integration tests

Integration tests should be placed in the tests/integration directory.
They can be run using the following command:

./avm integration-test

Integration tests should deploy real resources and should be run against a real Azure subscription.
However, they are not fully integrated into the AVM GitHub Actions workflows.
Authors should run integration tests locally and ensure that they are passing but they will not be run automatically in the CI/CD pipeline.