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"
    }
  }
}