Bicep Composition

Directory and File Structure

Each Bicep AVM module of the Azure/bicep-registry-modules (BRM) repository must be implemented as per the structure described in BCPNFR23.

For new modules, the files can be created automatically, once the parent folder exists. This example shows how to create a res module res/compute/virtual-machine.

Set-Location -Path ".\avm\"
New-Item -ItemType Directory -Path ".\res\compute\virtual-machine"
Set-AVMModule -ModuleFolderPath .\res\compute\virtual-machine

Code Styling

This section points to conventions to be followed when developing a Bicep template.

Casing

Use camelCasing as per BCPNFR8.

Input Parameters and Variables

Make sure to review all specifications of Category: Inputs/Outputs within the Bicep 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.

Modules

Modules enable you to reuse code from a Bicep file in other Bicep files. As such, for resource modules they’re normally leveraged for deploying child resources (e.g., file services in a storage account), cross referenced resources (e.g., network interface in a virtual machine) or extension resources (e.g., role assignments in a key vault). Pattern modules, normally reuse resource modules combined together.

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

Outputs

Make sure to review all specifications of Category: Inputs/Outputs within the Bicep specific 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 Bicep Interfaces page.
If the primary resource of the AVM resource module you are developing supports any of the listed features/extension resources, please follow the corresponding provided Bicep schema to develop them.

Deprecation

Breaking changes are sometimes not avoidable. The impact should be kept as low as possible. A recommendation is to deprecate parameters, instead of completely removing them for a couple of versions. The Semantic Versioning sections offers information about versioning AVM modules.

In case you need to deprecate an input parameter, this sample shows you how this can be achieved.

Example-Scenario

An AVM module is modified, and the parameters will change, which breaks backward compatibility.

• parameters are changing to a custom type
• the parameter structure is changing
• backward compatibility will be maintained

Existing input parameters used to be defined as follows (reducing the examples to the minimum):

// main.bicep:
param item object?

// main.test.bicep:
name: 'name'
item:
  {
    variant: 'Large'
    osType: 'Windows'
  }

Testing

Before you begin to modify anything, it is recommended to create a new test case (e.g. deprecated), in addition to the already existing tests, to make sure that the changes are not breaking backward compatibility until you decide to finally remove the deprecated parameters (see BCPRMNFR1 - Category: Testing - Expected Test Directories for more details about the requirements).

module testDeployment '../../../main.bicep' = [
  for iteration in ['init', 'idem']: {
    scope: resourceGroup
    name: '${uniqueString(deployment().name, resourceLocation)}-test-${serviceShort}-${iteration}'
    params: {
      name: '${namePrefix}${serviceShort}001'
      item: {
        variant: 'Large'
        osType: 'Linux'
      }
    }
  }
]

The test should include all previously used parameters to make sure they are covered before any changes to the new parameter layout are done.

Code Changes

The new parameter structure requires a change to the used parameters and moves them to a different location and looks like:

// main.bicep:
param item itemType?

type itemtype: {
  name: string // the name parameter did not change

  properties ={
    osType: 'Linux' | 'Windows'? // the new place for the osType

    variant: {
      size: string? // the new place for the variant size
    }?
  }

  // keep these for backward compatibility in the new type
  @description('Optional. Note: This is a deprecated property, please use the corresponding `properties.osType` instead.')
  osType: string? // the old parameter location

  @description('Optional. Note: This is a deprecated property, please use the corresponding `properties.variant.size` instead.')
  variant: string? // the old parameter location
}

The original parameter item is of type object and does not give the user any clue of what the syntax is and what is expected to be added to it. The tests could bring light into the darkness, but this is not ideal. In order to retain backward compatibility, the previously used parameters need to be added to the new type, as they would be invalid otherwise. Now that the new type is in place, some logic needs to be implemented to make sure the module can handle the different sources of data (new and old parameters).

resource <modulename> 'Microsoft.xy/yz@2024-01-01' = {
  name: name
  properties: {
    osType: item.?properties.?osType ?? item.?osType ?? 'Linux' // add a default here, if needed
    variant: {
      size: item.?properties.?variant.?size ?? item.?variant
    }
  }
}

By choosing this order for the Coalesce operator, the new format takes precedence over the old syntax. Also note the safe-dereference ensures that no null reference exception will occure if the property has optional parameters.

The tests can now be changed to adapt the new parameter structure for the new version of the module. They will not cover the old parameter structure anymore.

module testDeployment '../../../main.bicep' = [
  for iteration in ['init', 'idem']: {
    scope: resourceGroup
    name: '${uniqueString(deployment().name, resourceLocation)}-test-${serviceShort}-${iteration}'
    params: {
      name: '${namePrefix}${serviceShort}001'
      location: resourceLocation
      item:{
        osType: 'Linux'
        variant: {
          size: 'Large'
        }
      }
    }
  }
]

Summary

Changes to modules (resource or pattern) can bei implemented in two ways.

1. Implement changes with backward compatibility

   In this scenario, you need to make sure that the code does not break backward compatibility by:

   • adding new parameters
   • marking other parameters as deprecated
   • create a test case for the old usage syntax
   • increase the minor version number of the module (0.x)

2. Introduce breaking changes

   The easier way to introduce a new major version requires fewer steps:

   • adding new parameters
   • create a test case for the usage
   • increase the major version number of the module (x.0.0)

Bicep 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/bicep/bicep-contribution-flow/#1-fork-the-module-source-repository"
  B(2 - Configure a deployment identity in Azure)
    click B "/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#2-configure-a-deployment-identity-in-azure"
  C("3 - Configure CI environment for module tests")
    click C "/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#3-configure-your-ci-environment"
  D("4 - Implementing your contribution<br>(Refer to Gitflow Diagram below)")
    click D "/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#4-implement-your-contribution"
  E(5 - Workflow test completed successfully?)
    click E "/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#5-createupdate-and-run-tests"
  F(6 - Create a pull request to the upstream repository)
    click F "/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#6-create-a-pull-request-to-the-public-bicep-registry"
  G(7 - Get your pull request approved)
    click G "/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#7-get-your-pull-request-approved"
  A --> B
  B --> C
  C --> D
  D --> E
  E -->|yes|F
  E -->|no|D
  F --> G

GitFlow for contributors

The GitFlow process outlined here introduces a central anchor branch. This branch should be treated as if it were a protected branch. It serves to synchronize the forked repository with the original upstream repository. The use of the anchor branch is designed to give contributors the flexibility to work on several modules simultaneous.

---

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

gitGraph LR:
  commit id:"Fork Repo"
  branch anchor
  checkout anchor
  commit id:"Sync Upstream/main" type: HIGHLIGHT
  branch avm-type-provider-resource-workflow
  checkout avm-type-provider-resource-workflow
  commit id:"Add Workflow File for Resource/Pattern"
  branch avm-type-provider-resource
  checkout main
  merge avm-type-provider-resource-workflow id: "merge workflow for GitHub Actions Testing" type: HIGHLIGHT
  checkout avm-type-provider-resource
  commit id:"Init"
  commit id:"Patch 1"
  commit id:"Patch 2"
  checkout main
  merge avm-type-provider-resource

PowerShell Helper Script To Setup Fork & CI Test Environment

To simplify the setup of the fork, clone and configuration of the required GitHub Environments, Secrets, User-Assigned Managed Identity (UAMI), Federated Credentials and RBAC assignments in your Azure environment for the CI framework to function correctly in your fork, we have created a PowerShell script that you can use to do steps 1, 2 & 3 below.

The script performs the following steps:

1. Forks the Azure/bicep-registry-modules to your GitHub Account.
2. Clones the repo locally to your machine, based on the location you specify in the parameter: -GitHubRepositoryPathForCloneOfForkedRepository.
3. Prompts you and takes you directly to the place where you can enable GitHub Actions Workflows on your forked repo.
4. Disables all AVM module workflows, as per Enable or Disable Workflows.
5. Creates an User-Assigned Managed Identity (UAMI) and federated credentials for OIDC with your forked GitHub repo and grants it the RBAC roles of Owner at Management Group level, if specified in the -GitHubSecret_ARM_MGMTGROUP_ID parameter, and at Azure Subscription level if you provide it via the -GitHubSecret_ARM_SUBSCRIPTION_ID parameter.
6. Creates the required GitHub Environments & required Secrets in your forked repo as per step 3, based on the input provided in parameters and the values from resources the script creates and configures for OIDC. Also set the workflow permissions to Read and write permissions as per step 3.3.

Pre-requisites

1. You must have the Azure PowerShell Modules installed and you need to be logged with the context set to the desired Tenant. You must have permissions to create an SPN and grant RBAC over the specified Subscription and Management Group, if provided.
2. You must have the GitHub CLI installed and need to be authenticated with the GitHub user account you wish to use to fork, clone and work with on AVM.

.\<PATH-TO-SCRIPT-DOWNLOAD-LOCATION>\New-AVMBicepBRMForkSetup.ps1 -GitHubRepositoryPathForCloneOfForkedRepository "<pathToCreateForkedRepoIn>" -GitHubSecret_ARM_MGMTGROUP_ID "<managementGroupId>" -GitHubSecret_ARM_SUBSCRIPTION_ID "<subscriptionId>" -GitHubSecret_ARM_TENANT_ID "<tenantId>" -GitHubSecret_TOKEN_NAMEPREFIX "<unique3to5AlphanumericStringForAVMDeploymentNames>" -UAMIRsgLocation "<Azure Region/Location of your choice such as 'uksouth'>"

[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingWriteHost", "", Justification = "Coloured output required in this script")]

#Requires -PSEdition Core
#Requires -Modules @{ ModuleName="Az.Accounts"; ModuleVersion="2.19.0" }
#Requires -Modules @{ ModuleName="Az.Resources"; ModuleVersion="6.16.2" }

<#
.SYNOPSIS
This function creates and sets up everything a contributor to the AVM Bicep project should need to get started with their contribution to a AVM Bicep Module.

.DESCRIPTION
This function creates and sets up everything a contributor to the AVM Bicep project should need to get started with their contribution to a AVM Bicep Module. This includes:

- Forking and cloning the `Azure/bicep-registry-modules` repository
- Creating a new SPN and granting it the necessary permissions for the CI tests and configuring the forked repositories secrets, as per: https://azure.github.io/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#2-configure-a-deployment-identity-in-azure
- Enabling GitHub Actions on the forked repository
- Disabling all the module workflows by default, as per: https://azure.github.io/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/enable-or-disable-workflows/

Effectively simplifying this process to a single command, https://azure.github.io/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/

.PARAMETER GitHubRepositoryPathForCloneOfForkedRepository
Mandatory. The path to the GitHub repository to fork and clone. Directory will be created if does not already exist. Can use either relative paths or full literal paths.

.PARAMETER GitHubSecret_ARM_MGMTGROUP_ID
Optional. The group ID of the management group to test-deploy modules in. Is needed for resources that are deployed to the management group scope. If not provided CI tests on Management Group scoped modules will not work and you will need to manually configure the RBAC role assignments for the SPN and associated repository secret later.

.PARAMETER GitHubSecret_ARM_SUBSCRIPTION_ID
Mandatory. The ID of the subscription to test-deploy modules in. Is needed for resources that are deployed to the subscription scope.

.PARAMETER GitHubSecret_ARM_TENANT_ID
Mandatory. The tenant ID of the Azure Active Directory tenant to test-deploy modules in. Is needed for resources that are deployed to the tenant scope.

.PARAMETER GitHubSecret_TOKEN_NAMEPREFIX
Mandatory. Required. A short (3-5 character length), unique string that should be included in any deployment to Azure. Usually, AVM Bicep test cases require this value to ensure no two contributors deploy resources with the same name - which is especially important for resources that require a globally unique name (e.g., Key Vault). These characters will be used as part of each resource’s name during deployment.

.PARAMETER SPNName
Optional. The name of the SPN (Service Principal) to create. If not provided, a default name of `spn-avm-bicep-brm-fork-ci-<GitHub Organization>` will be used.

.PARAMETER UAMIName
Optional. The name of the UAMI (User Assigned Managed Identity) to create. If not provided, a default name of `id-avm-bicep-brm-fork-ci-<GitHub Organization>` will be used.

.PARAMETER UAMIRsgName
Optional. The name of the Resource Group to create for the UAMI (User Assigned Managed Identity) to create. If not provided, a default name of `rsg-avm-bicep-brm-fork-ci-<GitHub Organization>-oidc` will be used.

.PARAMETER UAMIRsgLocation
Optional. The location of the Resource Group to create for the UAMI (User Assigned Managed Identity) to create. Also UAMI will be created in this location. This is required for OIDC deployments.

.PARAMETER UseOIDC
Optional. Default is `$true`. If set to `$true`, the script will use the OIDC (OpenID Connect) authentication method for the SPN instead of secrets as per https://azure.github.io/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#31-set-up-secrets. If set to `$false`, the script will use the Client Secret authentication method for the SPN and not OIDC.

.EXAMPLE
.\<PATH-TO-SCRIPT-DOWNLOAD-LOCATION>\New-AVMBicepBRMForkSetup.ps1 -GitHubRepositoryPathForCloneOfForkedRepository "D:\GitRepos\" -GitHubSecret_ARM_MGMTGROUP_ID "alz" -GitHubSecret_ARM_SUBSCRIPTION_ID "1b60f82b-d28e-4640-8cfa-e02d2ddb421a" -GitHubSecret_ARM_TENANT_ID "c3df6353-a410-40a1-b962-e91e45e14e4b" -GitHubSecret_TOKEN_NAMEPREFIX "ex123" -UAMIRsgLocation "uksouth"

Example Subscription & Management Group scoped deployments enabled via OIDC with default generated UAMI Resource Group name of `rsg-avm-bicep-brm-fork-ci-<GitHub Organization>-oidc` and UAMI name of `id-avm-bicep-brm-fork-ci-<GitHub Organization>`.

.EXAMPLE
.\<PATH-TO-SCRIPT-DOWNLOAD-LOCATION>\New-AVMBicepBRMForkSetup.ps1 -GitHubRepositoryPathForCloneOfForkedRepository "D:\GitRepos\" -GitHubSecret_ARM_MGMTGROUP_ID "alz" -GitHubSecret_ARM_SUBSCRIPTION_ID "1b60f82b-d28e-4640-8cfa-e02d2ddb421a" -GitHubSecret_ARM_TENANT_ID "c3df6353-a410-40a1-b962-e91e45e14e4b" -GitHubSecret_TOKEN_NAMEPREFIX "ex123" -UAMIRsgLocation "uksouth" -UAMIName "my-uami-name" -UAMIRsgName "my-uami-rsg-name"

Example with provided UAMI Name & UAMI Resource Group Name.

.EXAMPLE
.\<PATH-TO-SCRIPT-DOWNLOAD-LOCATION>\New-AVMBicepBRMForkSetup.ps1 -GitHubRepositoryPathForCloneOfForkedRepository "D:\GitRepos\" -GitHubSecret_ARM_SUBSCRIPTION_ID "1b60f82b-d28e-4640-8cfa-e02d2ddb421a" -GitHubSecret_ARM_TENANT_ID "c3df6353-a410-40a1-b962-e91e45e14e4b" -GitHubSecret_TOKEN_NAMEPREFIX "ex123" -UseOIDC $false

DEPRECATED - USE OIDC INSTEAD.
Example Subscription scoped deployments enabled only with default generated SPN name of `spn-avm-bicep-brm-fork-ci-<GitHub Organization>`.

.EXAMPLE
.\<PATH-TO-SCRIPT-DOWNLOAD-LOCATION>\New-AVMBicepBRMForkSetup.ps1 -GitHubRepositoryPathForCloneOfForkedRepository "D:\GitRepos\" -GitHubSecret_ARM_MGMTGROUP_ID "alz" -GitHubSecret_ARM_SUBSCRIPTION_ID "1b60f82b-d28e-4640-8cfa-e02d2ddb421a" -GitHubSecret_ARM_TENANT_ID "c3df6353-a410-40a1-b962-e91e45e14e4b" -GitHubSecret_TOKEN_NAMEPREFIX "ex123" -SPNName "my-spn-name" -UseOIDC $false

DEPRECATED - USE OIDC INSTEAD.
Example with provided SPN name.

#>

[CmdletBinding(SupportsShouldProcess = $false)]
param (
  [Parameter(Mandatory = $true)]
  [string] $GitHubRepositoryPathForCloneOfForkedRepository,

  [Parameter(Mandatory = $false)]
  [string] $GitHubSecret_ARM_MGMTGROUP_ID,

  [Parameter(Mandatory = $true)]
  [string] $GitHubSecret_ARM_SUBSCRIPTION_ID,

  [Parameter(Mandatory = $true)]
  [string] $GitHubSecret_ARM_TENANT_ID,

  [Parameter(Mandatory = $true)]
  [string] $GitHubSecret_TOKEN_NAMEPREFIX,

  [Parameter(Mandatory = $false)]
  [string] $SPNName,

  [Parameter(Mandatory = $false)]
  [string] $UAMIName,

  [Parameter(Mandatory = $false)]
  [string] $UAMIRsgName = "rsg-avm-bicep-brm-fork-ci-oidc",

  [Parameter(Mandatory = $false)]
  [string] $UAMIRsgLocation,

  [Parameter(Mandatory = $false)]
  [bool] $UseOIDC = $true
)

# Check if the GitHub CLI is installed
$GitHubCliInstalled = Get-Command gh -ErrorAction SilentlyContinue
if ($null -eq $GitHubCliInstalled) {
  throw 'The GitHub CLI is not installed. Please install the GitHub CLI and try again. Install link for GitHub CLI: https://github.com/cli/cli#installation'
}
Write-Host 'The GitHub CLI is installed...' -ForegroundColor Green

# Check if GitHub CLI is authenticated
$GitHubCliAuthenticated = gh auth status
if ($LASTEXITCODE -ne 0) {
  Write-Host $GitHubCliAuthenticated -ForegroundColor Red
  throw "Not authenticated to GitHub. Please authenticate to GitHub using the GitHub CLI command of 'gh auth login', and try again."
}
Write-Host 'Authenticated to GitHub with following details...' -ForegroundColor Cyan
Write-Host ''
gh auth status
Write-Host ''

# Ask the user to confirm if it's the correct GitHub account
do {
  Write-Host "Is the above GitHub account correct to coninue with the fork setup of the 'Azure/bicep-registry-modules' repository? Please enter 'y' or 'n'." -ForegroundColor Yellow
  $userInput = Read-Host
  $userInput = $userInput.ToLower()

  switch ($userInput) {
    'y' {
      Write-Host ''
      Write-Host 'User Confirmed. Proceeding with the GitHub account listed above...' -ForegroundColor Green
      Write-Host ''
      break
    }
    'n' {
      Write-Host ''
      throw "User stated incorrect GitHub account. Please switch to the correct GitHub account. You can do this in the GitHub CLI (gh) by logging out by running 'gh auth logout' and then logging back in with 'gh auth login'"
    }
    default {
      Write-Host ''
      Write-Host "Invalid input. Please enter 'y' or 'n'." -ForegroundColor Red
      Write-Host ''
    }
  }
} while ($userInput -ne 'y' -and $userInput -ne 'n')

# Fork and clone repository locally
Write-Host "Changing to directory $GitHubRepositoryPathForCloneOfForkedRepository ..." -ForegroundColor Magenta

if (-not (Test-Path -Path $GitHubRepositoryPathForCloneOfForkedRepository)) {
  Write-Host "Directory does not exist. Creating directory $GitHubRepositoryPathForCloneOfForkedRepository ..." -ForegroundColor Yellow
  New-Item -Path $GitHubRepositoryPathForCloneOfForkedRepository -ItemType Directory -ErrorAction Stop
  Write-Host ''
}
Set-Location -Path $GitHubRepositoryPathForCloneOfForkedRepository -ErrorAction stop
$CreatedDirectoryLocation = Get-Location
Write-Host "Forking and cloning 'Azure/bicep-registry-modules' repository..." -ForegroundColor Magenta

gh repo fork 'Azure/bicep-registry-modules' --default-branch-only --clone=true
if ($LASTEXITCODE -ne 0) {
  throw "Failed to fork and clone the 'Azure/bicep-registry-modules' repository. Please check the error message above, resolve any issues, and try again."
}

$ClonedRepoDirectoryLocation = Join-Path $CreatedDirectoryLocation 'bicep-registry-modules'
Write-Host ''
Write-Host "Fork of 'Azure/bicep-registry-modules' created successfully directory in $CreatedDirectoryLocation ..." -ForegroundColor Green
Write-Host ''
Write-Host "Changing into cloned repository directory $ClonedRepoDirectoryLocation ..." -ForegroundColor Magenta
Set-Location $ClonedRepoDirectoryLocation -ErrorAction stop

# Check is user is logged in to Azure
$UserLoggedIntoAzure = Get-AzContext -ErrorAction SilentlyContinue
if ($null -eq $UserLoggedIntoAzure) {
  throw 'You are not logged into Azure. Please log into Azure using the Azure PowerShell module using the command of `Connect-AzAccount` to the correct tenant and try again.'
}
$UserLoggedIntoAzureJson = $UserLoggedIntoAzure | ConvertTo-Json -Depth 10 | ConvertFrom-Json
Write-Host "You are logged into Azure as '$($UserLoggedIntoAzureJson.Account.Id)' ..." -ForegroundColor Green

# Check user has access to desired subscription
$UserCanAccessSubscription = Get-AzSubscription -SubscriptionId $GitHubSecret_ARM_SUBSCRIPTION_ID -ErrorAction SilentlyContinue
if ($null -eq $UserCanAccessSubscription) {
  throw "You do not have access to the subscription with the ID of '$($GitHubSecret_ARM_SUBSCRIPTION_ID)'. Please ensure you have access to the subscription and try again."
}
Write-Host "You have access to the subscription with the ID of '$($GitHubSecret_ARM_SUBSCRIPTION_ID)' ..." -ForegroundColor Green
Write-Host ''

# Get GitHub Login/Org Name
$GitHubUserRaw = gh api user
$GitHubUserConvertedToJson = $GitHubUserRaw | ConvertFrom-Json -Depth 10
$GitHubOrgName = $GitHubUserConvertedToJson.login
$GitHubOrgAndRepoNameCombined = "$($GitHubOrgName)/bicep-registry-modules"

# Create SPN if not using OIDC
if ($UseOIDC -eq $false) {
  if ($SPNName -eq '') {
    Write-Host "No value provided for the SPN Name. Defaulting to 'spn-avm-bicep-brm-fork-ci-<GitHub Organization>' ..." -ForegroundColor Yellow

    $SPNName = "spn-avm-bicep-brm-fork-ci-$($GitHubOrgName)"
  }
  $newSpn = New-AzADServicePrincipal -DisplayName $SPNName -Description "Service Principal Name (SPN) for the AVM Bicep CI Tests in the $($GitHubOrgName) fork. See: https://azure.github.io/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/#2-configure-a-deployment-identity-in-azure" -ErrorAction Stop
  Write-Host "New SPN created with a Display Name of '$($newSpn.DisplayName)' and an Object ID of '$($newSpn.Id)'." -ForegroundColor Green
  Write-Host ''

  # Create RBAC Role Assignments for SPN
  Write-Host 'Starting 120 second sleep to allow the SPN to be created and available for RBAC Role Assignments (eventual consistency) ...' -ForegroundColor Yellow
  Start-Sleep -Seconds 120

  Write-Host "Creating RBAC Role Assignments of 'Owner' for the Service Principal Name (SPN) '$($newSpn.DisplayName)' on the Subscription with the ID of '$($GitHubSecret_ARM_SUBSCRIPTION_ID)' ..." -ForegroundColor Magenta
  New-AzRoleAssignment -ApplicationId $newSpn.AppId -RoleDefinitionName 'Owner' -Scope "/subscriptions/$($GitHubSecret_ARM_SUBSCRIPTION_ID)" -ErrorAction Stop
  Write-Host "RBAC Role Assignments of 'Owner' for the Service Principal Name (SPN) '$($newSpn.DisplayName)' created successfully on the Subscription with the ID of '$($GitHubSecret_ARM_SUBSCRIPTION_ID)'." -ForegroundColor Green
  Write-Host ''

  if ($GitHubSecret_ARM_MGMTGROUP_ID -eq '') {
    Write-Host "No Management Group ID provided as input parameter to '-GitHubSecret_ARM_MGMTGROUP_ID', skipping RBAC Role Assignments upon Management Groups" -ForegroundColor Yellow
    Write-Host ''
  }

  if ($GitHubSecret_ARM_MGMTGROUP_ID -ne '') {
    Write-Host "Creating RBAC Role Assignments of 'Owner' for the Service Principal Name (SPN) '$($newSpn.DisplayName)' on the Management Group with the ID of '$($GitHubSecret_ARM_MGMTGROUP_ID)' ..." -ForegroundColor Magenta
    New-AzRoleAssignment -ApplicationId $newSpn.AppId -RoleDefinitionName 'Owner' -Scope "/providers/Microsoft.Management/managementGroups/$($GitHubSecret_ARM_MGMTGROUP_ID)" -ErrorAction Stop
    Write-Host "RBAC Role Assignments of 'Owner' for the Service Principal Name (SPN) '$($newSpn.DisplayName)' created successfully on the Management Group with the ID of '$($GitHubSecret_ARM_MGMTGROUP_ID)'." -ForegroundColor Green
    Write-Host ''
  }
}

# Create UAMI if using OIDC
if ($UseOIDC) {
  if ($UAMIName -eq '') {
    Write-Host "No value provided for the UAMI Name. Defaulting to 'id-avm-bicep-brm-fork-ci-<GitHub Organization>' ..." -ForegroundColor Yellow

    $UAMIName = "id-avm-bicep-brm-fork-ci-$($GitHubOrgName)"
  }
  if ($UAMIRsgName -eq '') {
    Write-Host "No value provided for the UAMI Resource Group Name. Defaulting to 'rsg-avm-bicep-brm-fork-ci-<GitHub Organization>-oidc' ..." -ForegroundColor Yellow

    $UAMIRsgName = "rsg-avm-bicep-brm-fork-ci-$($GitHubOrgName)-oidc"
  }

  Write-Host "Selecting the subscription with the ID of '$($GitHubSecret_ARM_SUBSCRIPTION_ID)' to create Resource Group & UAMI in for OIDC ..." -ForegroundColor Magenta
  Select-AzSubscription -Subscription $GitHubSecret_ARM_SUBSCRIPTION_ID
  Write-Host ''

  if ($UAMIRsgLocation -eq '') {
    Write-Host "No value provided for the UAMI Location ..." -ForegroundColor Yellow
    $UAMIRsgLocation = Read-Host -Prompt "Please enter the location for the UAMI and the Resource Group to be created in for OIDC deployments. e.g. 'uksouth' or 'eastus', etc..."
    $UAMIRsgLocation = $UAMIRsgLocation.ToLower()

    $availableLocations = Get-AzLocation | Where-Object {$_.RegionType -eq 'Physical'} | Select-Object -ExpandProperty Location

    if ($availableLocations -notcontains $UAMIRsgLocation) {
      Write-Host "Invalid location provided. Please provide a valid location from the list below ..." -ForegroundColor Yellow
      Write-Host ''
      Write-Host "Available Locations: $($availableLocations -join ', ')" -ForegroundColor Yellow
      do {
        $UAMIRsgLocation = Read-Host -Prompt "Please enter the location for the UAMI and the Resource Group to be created in for OIDC deployments. e.g. 'uksouth' or 'eastus', etc..."
      } until (
        $availableLocations -icontains $UAMIRsgLocation
      )
    }
  }

  Write-Host "Creating Resource Group for UAMI with the name of '$($UAMIRsgName)' and location of '$($UAMIRsgLocation)'..." -ForegroundColor Magenta
  $newUAMIRsg = New-AzResourceGroup -Name $UAMIRsgName -Location $UAMIRsgLocation -ErrorAction Stop
  Write-Host "New Resource Group created with a Name of '$($newUAMIRsg.ResourceGroupName)' and a Location of '$($newUAMIRsg.Location)'." -ForegroundColor Green
  Write-Host ''

  Write-Host "Creating UAMI with the name of '$($UAMIName)' and location of '$($UAMIRsgLocation)' in the Resource Group with the name of '$($UAMIRsgName)..." -ForegroundColor Magenta
  $newUAMI = New-AzUserAssignedIdentity -ResourceGroupName $newUAMIRsg.ResourceGroupName -Name $UAMIName -Location $newUAMIRsg.Location -ErrorAction Stop
  Write-Host "New UAMI created with a Name of '$($newUAMI.Name)' and an Object ID of '$($newUAMI.PrincipalId)'." -ForegroundColor Green
  Write-Host ''

  Write-Host 'Starting 120 second sleep to allow the UAMI to be created and available for Federated Credential creation and RBAC Role Assignments (eventual consistency) ...' -ForegroundColor Yellow
  Start-Sleep -Seconds 120

  # Create Federated Credentials for UAMI for OIDC
  Write-Host "Creating Federated Credentials for the User-Assigned Managed Identity Name (UAMI) for OIDC ... '$($newUAMI.Name)' for OIDC ..." -ForegroundColor Magenta
  New-AzFederatedIdentityCredentials -ResourceGroupName $newUAMIRsg.ResourceGroupName -IdentityName $newUAMI.Name -Name 'avm-gh-env-validation' -Issuer "https://token.actions.githubusercontent.com" -Subject "repo:$($GitHubOrgAndRepoNameCombined):environment:avm-validation" -ErrorAction Stop
  Write-Host ''

  # Create RBAC Role Assignments for UAMI
  Write-Host "Creating RBAC Role Assignments of 'Owner' for the User-Assigned Managed Identity Name (UAMI) '$($newUAMI.Name)' on the Subscription with the ID of '$($GitHubSecret_ARM_SUBSCRIPTION_ID)' ..." -ForegroundColor Magenta
  New-AzRoleAssignment -ObjectId $newUAMI.PrincipalId -RoleDefinitionName 'Owner' -Scope "/subscriptions/$($GitHubSecret_ARM_SUBSCRIPTION_ID)" -ErrorAction Stop
  Write-Host "RBAC Role Assignments of 'Owner' for the User-Assigned Managed Identity Name (UAMI) '$($newUAMI.Name)' created successfully on the Subscription with the ID of '$($GitHubSecret_ARM_SUBSCRIPTION_ID)'." -ForegroundColor Green
  Write-Host ''

  if ($GitHubSecret_ARM_MGMTGROUP_ID -eq '') {
    Write-Host "No Management Group ID provided as input parameter to '-GitHubSecret_ARM_MGMTGROUP_ID', skipping RBAC Role Assignments upon Management Groups" -ForegroundColor Yellow
    Write-Host ''
  }

  if ($GitHubSecret_ARM_MGMTGROUP_ID -ne '') {
    Write-Host "Creating RBAC Role Assignments of 'Owner' for the User-Assigned Managed Identity Name (UAMI) '$($newSpn.DisplayName)' on the Management Group with the ID of '$($GitHubSecret_ARM_MGMTGROUP_ID)' ..." -ForegroundColor Magenta
    New-AzRoleAssignment -ObjectId $newUAMI.PrincipalId -RoleDefinitionName 'Owner' -Scope "/providers/Microsoft.Management/managementGroups/$($GitHubSecret_ARM_MGMTGROUP_ID)" -ErrorAction Stop
    Write-Host "RBAC Role Assignments of 'Owner' for the User-Assigned Managed Identity Name (UAMI) '$($newUAMI.Name)' created successfully on the Management Group with the ID of '$($GitHubSecret_ARM_MGMTGROUP_ID)'." -ForegroundColor Green
    Write-Host ''
  }
}

# Set GitHub Repo Secrets (non-OIDC)
if ($UseOIDC -eq $false) {
  Write-Host "Setting GitHub Secrets on forked repository (non-OIDC) '$($GitHubOrgAndRepoNameCombined)' ..." -ForegroundColor Magenta
  Write-Host 'Creating and formatting secret `AZURE_CREDENTIALS` with details from SPN creation process (non-OIDC) and other parameter inputs ...' -ForegroundColor Cyan

  $FormattedAzureCredentialsSecret = "{ 'clientId': '$($newSpn.AppId)', 'clientSecret': '$($newSpn.PasswordCredentials.SecretText)', 'subscriptionId': '$($GitHubSecret_ARM_SUBSCRIPTION_ID)', 'tenantId': '$($GitHubSecret_ARM_TENANT_ID)' }"
  $FormattedAzureCredentialsSecretJsonCompressed = $FormattedAzureCredentialsSecret | ConvertFrom-Json | ConvertTo-Json -Compress

  if ($GitHubSecret_ARM_MGMTGROUP_ID -ne '') {
    gh secret set ARM_MGMTGROUP_ID --body $GitHubSecret_ARM_MGMTGROUP_ID -R $GitHubOrgAndRepoNameCombined
  }
  gh secret set ARM_SUBSCRIPTION_ID --body $GitHubSecret_ARM_SUBSCRIPTION_ID -R $GitHubOrgAndRepoNameCombined
  gh secret set ARM_TENANT_ID --body $GitHubSecret_ARM_TENANT_ID -R $GitHubOrgAndRepoNameCombined
  gh secret set AZURE_CREDENTIALS --body $FormattedAzureCredentialsSecretJsonCompressed -R $GitHubOrgAndRepoNameCombined
  gh secret set TOKEN_NAMEPREFIX --body $GitHubSecret_TOKEN_NAMEPREFIX -R $GitHubOrgAndRepoNameCombined

  Write-Host ''
  Write-Host "Successfully created and set GitHub Secrets (non-OIDC) on forked repository '$($GitHubOrgAndRepoNameCombined)' ..." -ForegroundColor Green
  Write-Host ''
}

# Set GitHub Repo Secrets & Environment (OIDC)
if ($UseOIDC) {
  Write-Host "Setting GitHub Environment (avm-validation) and required Secrets on forked repository (OIDC) '$($GitHubOrgAndRepoNameCombined)' ..." -ForegroundColor Magenta
  Write-Host "Creating 'avm-validation' environment on forked repository' ..." -ForegroundColor Cyan

  $GitHubEnvironment = gh api --method PUT -H "Accept: application/vnd.github+json" "repos/$($GitHubOrgAndRepoNameCombined)/environments/avm-validation"
  $GitHubEnvironmentConvertedToJson = $GitHubEnvironment | ConvertFrom-Json -Depth 10

  if ($GitHubEnvironmentConvertedToJson.name -ne 'avm-validation') {
    throw "Failed to create 'avm-validation' environment on forked repository. Please check the error message above, resolve any issues, and try again."
  }

  Write-Host "Successfully created 'avm-validation' environment on forked repository' ..." -ForegroundColor Green
  Write-Host ''

  Write-Host "Creating and formatting secrets for 'avm-validation' environment with details from UAMI creation process (OIDC) and other parameter inputs ..." -ForegroundColor Cyan
  gh secret set VALIDATE_CLIENT_ID --body $newUAMI.ClientId -R $GitHubOrgAndRepoNameCombined -e 'avm-validation'
  gh secret set VALIDATE_SUBSCRIPTION_ID --body $GitHubSecret_ARM_SUBSCRIPTION_ID -R $GitHubOrgAndRepoNameCombined -e 'avm-validation'
  gh secret set VALIDATE_TENANT_ID --body $GitHubSecret_ARM_TENANT_ID -R $GitHubOrgAndRepoNameCombined -e 'avm-validation'

  Write-Host "Creating and formatting secrets for repo with details from UAMI creation process (OIDC) and other parameter inputs ..." -ForegroundColor Cyan
  if ($GitHubSecret_ARM_MGMTGROUP_ID -ne '') {
    gh secret set ARM_MGMTGROUP_ID --body $GitHubSecret_ARM_MGMTGROUP_ID -R $GitHubOrgAndRepoNameCombined
  }
  gh secret set ARM_SUBSCRIPTION_ID --body $GitHubSecret_ARM_SUBSCRIPTION_ID -R $GitHubOrgAndRepoNameCombined
  gh secret set ARM_TENANT_ID --body $GitHubSecret_ARM_TENANT_ID -R $GitHubOrgAndRepoNameCombined
  gh secret set TOKEN_NAMEPREFIX --body $GitHubSecret_TOKEN_NAMEPREFIX -R $GitHubOrgAndRepoNameCombined

  Write-Host ''
  Write-Host "Successfully created and set GitHub Secrets in 'avm-validation' environment and repo (OIDC) on forked repository '$($GitHubOrgAndRepoNameCombined)' ..." -ForegroundColor Green
  Write-Host ''
}

Write-Host "Opening browser so you can enable GitHub Actions on newly forked repository '$($GitHubOrgAndRepoNameCombined)' ..." -ForegroundColor Magenta
Write-Host "Please select click on the green button stating 'I understand my workflows, go ahead and enable them' to enable actions/workflows on your forked repository via the website that has appeared in your browser window and then return to this terminal session to continue ..." -ForegroundColor Yellow
Start-Process "https://github.com/$($GitHubOrgAndRepoNameCombined)/actions" -ErrorAction Stop
Write-Host ''

$GitHubWorkflowPlatformToggleWorkflows = '.Platform - Toggle AVM workflows'
$GitHubWorkflowPlatformToggleWorkflowsFileName = 'platform.toggle-avm-workflows.yml'

do {
  Write-Host "Did you successfully enable the GitHub Actions/Workflows on your forked repository '$($GitHubOrgAndRepoNameCombined)'? Please enter 'y' or 'n'." -ForegroundColor Yellow
  $userInput = Read-Host
  $userInput = $userInput.ToLower()

  switch ($userInput) {
    'y' {
      Write-Host ''
      Write-Host "User Confirmed. Proceeding to trigger workflow of '$($GitHubWorkflowPlatformToggleWorkflows)' to disable all workflows as per: https://azure.github.io/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/enable-or-disable-workflows/..." -ForegroundColor Green
      Write-Host ''
      break
    }
    'n' {
      Write-Host ''
      Write-Host 'User stated no. Ending script here. Please review and complete any of the steps you have not completed, likely just enabling GitHub Actions/Workflows on your forked repository and then disabling all workflows as per: https://azure.github.io/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/enable-or-disable-workflows/' -ForegroundColor Yellow
      exit
    }
    default {
      Write-Host ''
      Write-Host "Invalid input. Please enter 'y' or 'n'." -ForegroundColor Red
      Write-Host ''
    }
  }
} while ($userInput -ne 'y' -and $userInput -ne 'n')

Write-Host "Setting Read/Write Workflow permissions on forked repository '$($GitHubOrgAndRepoNameCombined)' ..." -ForegroundColor Magenta
gh api --method PUT -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" "/repos/$($GitHubOrgAndRepoNameCombined)/actions/permissions/workflow" -f "default_workflow_permissions=write"
Write-Host ''

Write-Host "Triggering '$($GitHubWorkflowPlatformToggleWorkflows) on '$($GitHubOrgAndRepoNameCombined)' ..." -ForegroundColor Magenta
Write-Host ''
gh workflow run $GitHubWorkflowPlatformToggleWorkflows -R $GitHubOrgAndRepoNameCombined
Write-Host ''

Write-Host 'Starting 120 second sleep to allow the workflow run to complete ...' -ForegroundColor Yellow
Start-Sleep -Seconds 120
Write-Host ''

Write-Host "Workflow '$($GitHubWorkflowPlatformToggleWorkflows) on '$($GitHubOrgAndRepoNameCombined)' should have now completed, opening workflow in browser so you can check ..." -ForegroundColor Magenta
Start-Process "https://github.com/$($GitHubOrgAndRepoNameCombined)/actions/workflows/$($GitHubWorkflowPlatformToggleWorkflowsFileName)" -ErrorAction Stop
Write-Host ''

Write-Host "Script execution complete. Fork of '$($GitHubOrgAndRepoNameCombined)' created and configured and cloned to '$($ClonedRepoDirectoryLocation)' as per Bicep contribution guide: https://azure.github.io/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/ you are now ready to proceed from step 4. Opening the Bicep Contribution Guide for you to review and continue..." -ForegroundColor Green
Start-Process 'https://azure.github.io/Azure-Verified-Modules/contributing/bicep/bicep-contribution-flow/'

1. Fork the module source repository

Bicep AVM Modules (Resource, Pattern and Utility modules) are located in the /avm directory of the Azure/bicep-registry-modules repository, as per SNFR19.

Module owners are expected to fork the Azure/bicep-registry-modules repository and work on a branch from within their fork, before creating a Pull Request (PR) back into the Azure/bicep-registry-modules repository’s upstream main branch.

To do so, simply navigate to the Public Bicep Registry 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’.

1.1 Create a GitHub environment

Create the avm-validation environment in your fork.

2. Configure a deployment identity in Azure

AVM tests its modules via deployments in an Azure subscription. To do so, it requires a deployment identity with access to it.

3. Configure your CI environment

To configure the forked CI environment you have to perform several steps:

• 3.1 Set up secrets
• 3.2 Enable actions
• 3.3 Set Read/Write Workflow permissions

3.1. Set up secrets

3.1.1 Shared repository secrets

To use the Continuous Integration environment’s workflows you should set up the following repository secrets:

3.1.2 Authentication secrets

In addition to shared repository secrets detailed above, additional GitHub secrets are required to allow the deploying identity to authenticate to Azure.

Expand and follow the option corresponding to the deployment identity setup chosen at Step 2 and use the information you gathered during that step.

{"clientId": "<client_id>", "clientSecret": "<client_secret>", "subscriptionId": "<subscriptionId>", "tenantId": "<tenant_id>" }

3.2. Enable actions

Finally, ‘GitHub Actions’ are disabled by default and hence, must be enabled first.

To do so, perform the following steps:

1. Navigate to the Actions tab on the top of the repository page.

2. Next, select ‘I understand my workflows, go ahead and enable them’.

   

3.3. Set Read/Write Workflow permissions

To let the workflow engine publish their results into your repository, you have to enable the read / write access for the GitHub actions.

1. Navigate to the Settings tab on the top of your repository page.

2. Within the section Code and automation click on Actions and General

3. Make sure to enable Read and write permissions

   

4. Implement your contribution

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

If you’re working on a new module, we’d also ask you to create its corresponding workflow file. Each module has its own file, but only differs in very few details, such as its triggers and pipeline variables. As a result, you can either copy & update any other module workflow file (starting with 'avm.[res|ptn|utl].') or leverage the following template:

# >>> UPDATE to for example "avm.res.key-vault.vault" and remove this comment
name: "avm.[res|ptn|utl].[provider-namespace].[resource-type]"

on:
  workflow_dispatch:
    inputs:
      staticValidation:
        type: boolean
        description: "Execute static validation"
        required: false
        default: true
      deploymentValidation:
        type: boolean
        description: "Execute deployment validation"
        required: false
        default: true
      removeDeployment:
        type: boolean
        description: "Remove deployed module"
        required: false
        default: true
      customLocation:
        type: string
        description: "Default location overwrite (e.g., eastus)"
        required: false
  push:
    branches:
      - main
    paths:
        # >>> UPDATE to for example ".github/workflows/avm.res.key-vault.vault.yml" and remove this comment
      - ".github/workflows/avm.[res|ptn|utl].[provider-namespace].[resource-type].yml"
        # >>> UPDATE to for example "avm/res/key-vault/vault/**" and remove this comment
      - "avm/[res|ptn|utl]/[provider-namespace]/[resource-type]/**"
      - "!*/**/README.md"

env:
  # >>> UPDATE to for example "avm/res/key-vault/vault" and remove this comment
  modulePath: "avm/[res|ptn|utl]/[provider-namespace]/[resource-type]"
  # >>> Update to for example ".github/workflows/avm.res.key-vault.vault.yml" and remove this comment
  workflowPath: ".github/workflows/avm.[res|ptn|utl].[provider-namespace].[resource-type].yml"

concurrency:
  group: ${{ github.workflow }}

jobs:
  ###########################
  #   Initialize pipeline   #
  ###########################
  job_initialize_pipeline:
    runs-on: ubuntu-latest
    name: "Initialize pipeline"
    if: ${{ !cancelled() && !(github.repository != 'Azure/bicep-registry-modules' && github.event_name != 'workflow_dispatch') }}
    steps:
      - name: "Checkout"
        uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - name: "Set input parameters to output variables"
        id: get-workflow-param
        uses: ./.github/actions/templates/avm-getWorkflowInput
        with:
          workflowPath: "${{ env.workflowPath}}"
      - name: "Get module test file paths"
        id: get-module-test-file-paths
        uses: ./.github/actions/templates/avm-getModuleTestFiles
        with:
          modulePath: "${{ env.modulePath }}"
    outputs:
      workflowInput: ${{ steps.get-workflow-param.outputs.workflowInput }}
      moduleTestFilePaths: ${{ steps.get-module-test-file-paths.outputs.moduleTestFilePaths }}
      psRuleModuleTestFilePaths: ${{ steps.get-module-test-file-paths.outputs.psRuleModuleTestFilePaths }}
      modulePath: "${{ env.modulePath }}"

  ##############################
  #   Call reusable workflow   #
  ##############################
  call-workflow-passing-data:
    name: "Run"
    permissions:
      id-token: write # For OIDC
      contents: write # For release tags
    needs:
      - job_initialize_pipeline
    uses: ./.github/workflows/avm.template.module.yml
    with:
      workflowInput: "${{ needs.job_initialize_pipeline.outputs.workflowInput }}"
      moduleTestFilePaths: "${{ needs.job_initialize_pipeline.outputs.moduleTestFilePaths }}"
      psRuleModuleTestFilePaths: "${{ needs.job_initialize_pipeline.outputs.psRuleModuleTestFilePaths }}"
      modulePath: "${{ needs.job_initialize_pipeline.outputs.modulePath}}"
    secrets: inherit

# Only run if not canceled and not in a fork, unless triggered by a workflow_dispatch event
if: ${{ !cancelled() && !(github.repository != 'Azure/bicep-registry-modules' && github.event_name != 'workflow_dispatch') }}

5. Create/Update and run tests

Before opening a Pull Request to the Bicep Public Registry, ensure your module is ready for publishing, by validating that it meets all the Testing Specifications as per SNFR1, SNFR2, SNFR3, SNFR4, SNFR5, SNFR6, SNFR7.

For example, to meet SNFR2, ensure the updated module is deployable against a testing Azure subscription and compliant with the intended configuration.

Depending on the type of contribution you implemented (for example, a new resource module feature) we would kindly ask you to also update the e2e test run by the pipeline. For a new parameter this could mean to either add its usage to an existing test file, or to add an entirely new test as per BCPRMNFR1.

Once the contribution is implemented and the changes are pushed to your forked repository, we kindly ask you to validate your updates in your own cloud environment before requesting to merge them to the main repo. Test your code leveraging the forked AVM CI environment you configured before

Creating end-to-end tests

As per BCPRMNFR1, a resource module must contain a minimum set of deployment test cases, while for pattern modules there is no restriction on the naming each deployment test must have.
In either case, you’re free to implement any additional, meaningful test that you see fit. Each test is implemented in its own test folder, containing at least a main.test.bicep and optionally any amount of extra deployment files that you may require (e.g., to deploy dependencies using a dependencies.bicep that you reference in the test template file).

To get started implementing your test in the main.test.bicep file, we recommend the following guidelines:

• As per BCPNFR13, each main.test.bicep file should implement metadata to render the test more meaningful in the documentation

• The main.test.bicep file should deploy any immediate dependencies (e.g., a resource group, if required) and invoke the module’s main template while providing all parameters for a given test scenario.

• Parameters

  • Each file should define a parameter serviceShort. This parameter should be unique to this file (i.e, no two test files should share the same) as it is injected into all resource deployments, making them unique too and account for corresponding requirements.

    • As a reference you can create a identifier by combining a substring of the resource type and test scenario (e.g., in case of a Linux Virtual Machine Deployment: vmlin).

    • For the substring, we recommend to take the first character and subsequent ‘first’ character from the resource type identifier and combine them into one string. Following you can find a few examples for reference:

      • db-for-postgre-sql/flexible-server with a test folder default could be: dfpsfsdef
      • storage/storage-account with a test folder waf-aligned could be: ssawaf

      💡 If the combination of the servicesShort with the rest of a resource name becomes too long, it may be necessary to bend the above recommendations and shorten the name.
      This can especially happen when deploying resources such as Virtual Machines or Storage Accounts that only allow comparatively short names.

  • If the module deploys a resource-group-level resource, the template should further have a resourceGroupName parameter and subsequent resource deployment. As a reference for the default name you can use dep-<namePrefix><providerNamespace>.<resourceType>-${serviceShort}-rg.

  • Each file should also provide a location parameter that may default to the deployments default location

• It is recommended to define all major resource names in the main.test.bicep file as it makes later maintenance easier. To implement this, make sure to pass all resource names to any referenced module (including any resource deployed in the dependencies.bicep).

• Further, for any test file (including the dependencies.bicep file), the usage of variables should be reduced to the absolute minimum. In other words: You should only use variables if you must use them in more than one place. The idea is to keep the test files as simple as possible

• References to dependencies should be implemented using resource references in combination with outputs. In other words: You should not hardcode any references into the module template’s deployment. Instead use references such as nestedDependencies.outputs.managedIdentityPrincipalId

  Important

  As per BCPNFR12 you must use the header module testDeployment '../.*main.bicep' = when invoking the module’s template.

  Tip

  📜 Example of test file

Dependency file (dependencies.bicep) guidelines:

• The dependencies.bicep should optionally be used if any additional dependencies must be deployed into a nested scope (e.g. into a deployed Resource Group).

• Note that you can reuse many of the assets implemented in other modules. For example, there are many recurring implementations for Managed Identities, Key Vaults, Virtual Network deployments, etc.

• A special case to point out is the implementation of Key Vaults that require purge protection (for example, for Customer Managed Keys). As this implies that we cannot fully clean up a test deployment, it is recommended to generate a new name for this resource upon each pipeline run using the output of the utcNow() function at the time.

  Tip

  📜 Example of test using purge protected Key Vault dependency

  Tip

  📜 If your test case requires any value that you cannot / should not specify in the test file itself (e.g., tenant-specific object IDs or secrets), please refer to the Custom CI secrets feature.

Reusable assets

The e2e template assets provide additional scripts and utilities that may be of use to module owners/contributors. These contain both scripts and Bicep templates that you can re-use in your test files (e.g., to deploy standadized dependencies, or to generate keys using deployment scripts).

Example: Certificate creation script

If you need a Deployment Script to set additional non-template resources up (for example certificates/files, etc.), we recommend to store it as a file in the shared utilities/e2e-template-assets/scripts folder and load it using the template function loadTextContent() (for example: scriptContent: loadTextContent('../../../../../../utilities/e2e-template-assets/scripts/New-SSHKey.ps1')). This approach makes it easier to test & validate the logic and further allows reusing the same logic across multiple test cases.

Example: Diagnostic Settings dependencies

To test the numerous diagnostic settings targets (Log Analytics Workspace, Storage Account, Event Hub, etc.) the AVM core team have provided a dependencies .bicep file to help create all these pre-requisite targets that will be needed during test runs.

// ========== //
// Parameters //
// ========== //

@description('Required. The name of the storage account to create.')
@maxLength(24)
param storageAccountName string

@description('Required. The name of the log analytics workspace to create.')
param logAnalyticsWorkspaceName string

@description('Required. The name of the event hub namespace to create.')
param eventHubNamespaceName string

@description('Required. The name of the event hub to create inside the event hub namespace.')
param eventHubNamespaceEventHubName string

@description('Optional. The location to deploy resources to.')
param location string = resourceGroup().location

// ============ //
// Dependencies //
// ============ //

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-08-01' = {
  name: storageAccountName
  location: location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
  properties: {
    allowBlobPublicAccess: false
  }
}

resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2021-12-01-preview' = {
  name: logAnalyticsWorkspaceName
  location: location
}

resource eventHubNamespace 'Microsoft.EventHub/namespaces@2021-11-01' = {
  name: eventHubNamespaceName
  location: location

  resource eventHub 'eventhubs@2021-11-01' = {
    name: eventHubNamespaceEventHubName
  }

  resource authorizationRule 'authorizationRules@2021-06-01-preview' = {
    name: 'RootManageSharedAccessKey'
    properties: {
      rights: [
        'Listen'
        'Manage'
        'Send'
      ]
    }
  }
}

// ======= //
// Outputs //
// ======= //

@description('The resource ID of the created Storage Account.')
output storageAccountResourceId string = storageAccount.id

@description('The resource ID of the created Log Analytics Workspace.')
output logAnalyticsWorkspaceResourceId string = logAnalyticsWorkspace.id

@description('The resource ID of the created Event Hub Namespace.')
output eventHubNamespaceResourceId string = eventHubNamespace.id

@description('The resource ID of the created Event Hub Namespace Authorization Rule.')
output eventHubAuthorizationRuleId string = eventHubNamespace::authorizationRule.id

@description('The name of the created Event Hub Namespace Event Hub.')
output eventHubNamespaceEventHubName string = eventHubNamespace::eventHub.name

6. Create a Pull Request to the Public Bicep Registry

Finally, once you are satisfied with your contribution and validated it, open a PR for the module owners or core team to review. Make sure you:

1. Provide a meaningful title in the form of feat: <module name> to align with the Semantic PR Check.

2. Provide a meaningful description.

3. Follow instructions you find in the PR template.

4. If applicable (i.e., a module is created/updated), please reference the badge status of your pipeline run. This badge will show the reviewer that the code changes were successfully validated & tested in your environment. To create a badge, first select the three dots (...) at the top right of the pipeline, and then chose the Create status badge option.

   

5. In the opening pop-up, you first need to select your branch and then click on the Copy status badge Markdown

   

7. Get your pull request approved

To publish a new module or a new version of an existing module, each Pull Request (PR) MUST be reviewed and approved before being merged and published in the Public Bicep Registry. A contributor (the submitter of the PR) cannot approve their own PR.

This behavior is assisted by policies, bots, through automatic assignment of the expected reviewer(s) and supporting labels.

7.1. Publishing a new module

When publishing a net new module for the first time ever, the PR MUST be reviewed and approved by a member of the core team.

7.2. Publishing a new version of an existing module

When publishing a new version of an existing module (i.e., anything that is not being published for the first time ever), the PR approval logic is the following:

In case of Bicep modules, if the PR includes any changes outside of the “modules/” folder, it first needs the module related code changes need to be reviewed and approved as per the above table, and only then does the PR need to be approved by a member of the core team. This way the core team’s approval does not act as a bypass from the actual code review perspective.

Bicep Contribution Prerequisites

GitHub Account Link and Access

You need to have a personal GitHub account which is linked to your Microsoft corporate identity. Once the link step is complete you must join the Azure organization.

Recommended Learning

Before you start contributing to the AVM, it is highly recommended that you complete the following Microsoft Learn paths, modules & courses:

Bicep

• Deploy and manage resources in Azure by using Bicep
• Bicep file structure and syntax
• Best practices for Bicep

Git

• Introduction to version control with Git

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"

• Bicep

  Note

  Must be manually kept up-to-date.

• Pester

• Visual Studio Code

  • Bicep extension for Visual Studio Code

Recommended Tooling

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

Visual Studio Code Extensions

• CodeTour extension for Visual Studio Code
• ARM Tools extension for Visual Studio Code
• ARM Template Viewer extension for Visual Studio Code
• PSRule extension for Visual Studio Code
• EditorConfig for VS Code
• For visibility of Bracket Pairs:
  • Inside Visual Studio Code, add editor.bracketPairColorization.enabled: true to your settings.json, to enable bracket pair colorization.

Desktop Tooling

• GitHub Desktop
  • To enhance streamlined integration during interactions with upstream repositories, GitHub Desktop will automatically configure your local git repository to use the upstream repository as a remote.

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. For a new module, confirm first that every control-plane resource and supported data-plane operation uses AzAPI. Any AzureRM block must satisfy and document the unsupported data-plane exception in TFFR3.

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:

Terraform configurations created for examples, end-to-end tests, tests, or fixtures are part of the module repository and MUST follow TFFR3. Use AzAPI for every supporting control-plane resource. AzureRM may be configured or exercised only when the test covers the module’s documented unsupported data-plane operation; it must not be used to make setup more convenient.

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. The azurerm segment in this legacy repository name is not a provider choice; modules created from the template MUST use AzAPI.

• 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; each submodule root MUST be a direct modules/<name>/ child)
• examples/ - (all examples must deploy successfully without requiring input and use AzAPI for supporting control-plane resources; AzureRM may appear only when exercising the module’s documented unsupported data-plane exception - these are customer facing and run as end-to-end tests)
  • <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> - (each example root MUST be a direct examples/<name>/ child)
• /... - (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.

Nested Terraform module and example roots are prohibited. Avm.Authoring convention validation enforces the one-layer modules/* and examples/* structure; see TFRMNFR1.

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.

Mandatory AzAPI patterns

Every Terraform AVM module MUST be built with AzAPI, and every 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 enabled by default through main.telemetry.tf, which is generated and maintained by Avm.Authoring. 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.
   • Confirm every control-plane resource and supported data-plane operation uses AzAPI across the root module, submodules, examples/e2e tests, Terraform tests, fixtures, and documentation snippets. Any AzureRM block must implement and document the narrow TFFR3 unsupported data-plane exception.
   • 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
   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. See the AVM TFLint rules guide for every enabled AVM rule, its applicability, exact disable block, and override precedence.

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.

The target-directory override takes precedence over the matching repository-wide scope override and applies only to that direct submodule or example. AVM permits only modules/* and examples/* Terraform roots; nested module or example roots are prohibited and rejected by Avm.Authoring convention validation. Use a target override instead of weakening an all-submodule or all-example override.

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.

AVM TFLint Rules

This reference covers the custom AVM TFLint ruleset rules. It does not repeat rules provided by the standard Terraform TFLint plugin. AVM rules are enabled by default. An override is an exception to an AVM requirement and should be narrow, temporary where possible, and explained in the override file.

Rule applicability and overrides

Rules run in the scope that contains the applicable Terraform configuration:

• All module scopes - the root module, each submodule, and each example independently.
• Module scopes - the root module and each submodule independently; examples are excluded.
• Root module - the published module root only.

To disable a rule, use the exact HCL shown in the Disable column. The configuration files and precedence rules are documented in TFLint configuration overrides.

Rule guidance

azapi data response export values

Applies TFFR4 to AzAPI data sources: declare response_export_values, including [] when no response fields are needed.

azapi replace triggers refs

Applies TFFR5. Omit replace_triggers_refs when no body paths require replacement. When present, it must be a non-empty static list of valid JMESPath expressions that identify body paths requiring replacement. Entries cannot be blank or duplicated, and cannot include name or location, because AzAPI already replaces the resource when either changes. When the body is statically evaluable, the rule verifies that each declared path resolves against it.

Authors remain responsible for identifying the properties that actually require replacement. Current Bicep-generated schemas do not reliably preserve create-only versus updateable mutability, so this rule validates declared paths but cannot prove that the list is semantically complete.

azapi resource tag

Applies TFFR9: set tags = var.tags exactly on types supported by the embedded AVM-generated capability snapshot, and omit tags for unsupported types. The rule skips dynamic or otherwise unevaluable type expressions.

The ruleset embeds its AVM-generated capability snapshot and works standalone. It does not consume, import, or query AzAPI, and does not accept an external snapshot path.

A weekly ruleset workflow compares the embedded snapshot with upstream data and opens a ruleset pull request when that data changes. Updated capability data ships with the next ruleset release. All users receive snapshot updates by upgrading the ruleset release.

azapi response export values

Applies TFFR4: every applicable managed AzAPI resource declares response_export_values, including [] when no fields are exported.

customer managed key

Validates the customer-managed key interface.

deprecated lock interface

Prevents new use of deprecated shapes in the resource-lock interface.

deprecated private endpoints interface

Prevents new use of deprecated shapes in the private-endpoints interface.

deprecated role assignments interface

Prevents new use of deprecated shapes in the role-assignments interface.

diagnostic settings

Validates the diagnostic-settings interface.

ignore body changes

Validates the AzAPI ignore_body_changes interface, including its per-resource and per-submodule applicability.

location

Validates the standard location interface.

lock

Validates the resource-lock interface.

managed identities

Validates the managed-identities interface.

no entire resource output tffr2

Applies TFFR2: output explicit values instead of an entire provider resource.

private endpoints

Validates the private-endpoints interface.

private endpoints manage dns zone group

Validates the DNS-zone-group behavior of the private-endpoints interface.

provider azapi version constraint

Validates the AzAPI constraint required by TFFR3.

provider azurerm disallowed

Applies the AzureRM-foundation prohibition in TFFR3.

provider azurerm version constraint

Validates the AzureRM constraint when the narrow TFFR3 exception is used.

provider modtm version constraint

Validates the ModTM provider constraint when that provider is used.

required module source tffr1

Applies TFFR1 to AVM module sources.

required module source tfnfr10

Applies TFNFR10 to ignore_changes references.

required output rmfr7

Applies the required-output contract in RMFR7.

resource types

Validates the AzAPI resource_types interface, including its deterministic resource-type keys and cascading shape.

retry

Validates the AzAPI retry interface.

role assignments

Validates the role-assignments interface.

tags

Validates the tags interface.

terraform heredoc usage

Applies TFNFR40: represent JSON or YAML structured values with jsonencode or yamlencode.

terraform module provider declaration

Applies TFNFR27: a published module contains no provider blocks; aliases are declared only through configuration_aliases and configured by its consumer.

terraform sensitive variable no default

Applies TFNFR23: a sensitive variable may default only to an empty collection.

terraform tf file

Applies TFNFR39: a module has exactly one terraform block and it is in terraform.tf.

timeouts

Validates the AzAPI timeouts interface.

MAPOTF and standard Terraform TFLint coverage

MAPOTF, not a custom AVM TFLint rule, owns formatting and deterministic ordering for resource and data blocks, variables, outputs, required providers, and file placement. It also removes redundant explicit nullable = true; that cleanup does not replace the semantic requirements for nullable = false in TFNFR20 and TFNFR21.

The standard Terraform TFLint plugin validates required_version and provider requirement declarations. TFNFR25 and TFNFR26 explain the complementary AVM file-layout and ordering requirements.

TFLint configuration overrides

Avm.Authoring loads the following repository-root override files:

Each file contains normal TFLint rule configuration. For example:

rule "terraform_sensitive_variable_no_default" {
  enabled = false
}

Avm.Authoring merges overrides in this order: the immutable AVM base configuration, the matching repository-root all-scope override, then the target-directory override. A submodule or example override is loaded only for its target directory and takes precedence over the matching all-submodule or all-example file. Use it when an exception is specific to one direct child module or example; do not weaken the corresponding repository-wide default.

AVM permits only one directory layer for Terraform submodule and example roots: modules/* and examples/*. Nested Terraform module or example roots are prohibited, so target overrides apply only to those direct scopes. Avm.Authoring convention validation enforces this structure.