Terraform Composition

Important

This guide MUST be used in conjunction with the Terraform specifications. ALL AVM modules (Resource and Pattern modules) MUST meet the respective requirements described in these specifications!

Repositories

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

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

Directory and File Structure

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

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

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.

Tip

See examples in specifications SNFR14 and TFFR14.

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.

Tip

See examples in specifications SFR1 and RMFR1.

Outputs

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

Tip

See examples in specification RMFR7 and TFFR2.

Interfaces

Note

This section is only relevant for contributions to resource modules.

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

Please refer to the Terraform Interfaces page.

Required AzAPI patterns

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

Spec	One-liner
TFRMFR1	Expose the parent scope as a single required `parent_id` string variable. Do not expose `resource_group_name` or any other scope-specific input. Validate with `provider::azapi::parse_resource_id` against the expected parent type.
TFRMNFR1	Implement every ARM subresource as a Terraform submodule under `modules/<subresource-singular-name>/`. Parent modules MUST reference submodules, and submodules MUST be independently consumable. Keep submodule primary resources single-instance only (no `count` / `for_each` on `azapi_resource.this`); cardinality belongs at the module call site.
TFRMNFR2	Name the primary `azapi_resource` `this`. Satellite resources MUST be named after what they represent (e.g. `azapi_resource.lock`, `azapi_resource.role_assignment`, `azapi_resource.diagnostic_setting`, `azapi_resource.private_endpoint`), not `this`.
TFFR4	Always set `response_export_values` on every AzAPI resource (use `[]` when nothing needs exporting). Include any read-only properties the module’s outputs or downstream resources depend on.
TFFR5	Always set `replace_triggers_refs` on every AzAPI resource. List the body paths that MUST force replacement when they change; `name` and `location` are already triggers, so don’t repeat them.
TFFR6	Source the `type` argument of every AzAPI resource from a single `resource_types` object variable instead of hard-coding type strings. Use one optional key per resource, defaulted to the tested API version, and cascade the relevant subset to each submodule.
TFFR7	Expose `retry` and `timeouts` variables, apply them to every `azapi_resource`, and cascade them to every submodule.
TFNFR38	Validate every variable (or nested attribute) that holds an Azure ARM resource ID using `can(provider::azapi::parse_resource_id("Microsoft.X/y", value))`. Hand-rolled regex / `startswith` / `length` checks MUST NOT be used.
TFNFR39	Use the standard file layout (`terraform.tf`, `variables.tf`, `outputs.tf`, `main.tf`, `locals.tf`). Larger modules MAY split `main.tf` into `main.<topic>.tf` files.

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

Telemetry

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

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

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

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