Terraform Specifications

Specifications by Category and Module Classification

How to propose changes to the specifications?

AzAPI is mandatory for AVM Terraform modules

Every new AVM Terraform module — resource, pattern, or utility — MUST use the AzAPI provider for every control-plane resource and supported data-plane operation. This applies throughout the module repository, including submodules, examples, end-to-end tests, Terraform tests, fixtures, and documentation snippets.

AzureRM is permitted only for a specific data-plane/non-ARM API operation that AzAPI cannot implement, under the narrow exception in TFFR3. It is never permitted for an ARM control-plane resource or as a convenience alternative to AzAPI.

This requirement is intentional and is driven by the following factors:

• Built-in retries and error handling. AzAPI exposes first-class retry and timeouts blocks, including regex-based error matching, which lets modules handle transient failures (for example, scope locks being removed or eventual-consistency errors) deterministically and without external workarounds.
• Pre-flight validation. AzAPI performs ARM API pre-flight checks at plan time, surfacing many configuration errors before an apply is attempted. This produces faster feedback loops and fewer partially-deployed resources.
• Day-zero access to the latest Azure features. Because AzAPI talks directly to the Azure Resource Manager REST API, modules can adopt new resource types, properties and API versions as soon as they ship in Azure — without waiting for an AzureRM provider release.
• Alignment with Bicep and ARM. AzAPI uses the same resource type identifiers (e.g. Microsoft.KeyVault/vaults@2023-07-01) and the same property shape as Bicep and ARM templates. This makes it dramatically easier to translate documentation, samples and Bicep modules into Terraform, and keeps Bicep and Terraform AVM modules conceptually aligned.
• Close partnership with the Azure engineering teams. AzAPI is built and maintained in close collaboration with the Azure Resource Provider engineering teams. Issues in AzAPI can be triaged directly against the underlying ARM behavior, and the AVM team works directly with the AzAPI engineering team on roadmap and breaking changes.
• Consistency across the AVM ecosystem. Standardizing on AzAPI means every AVM Terraform module uses the same patterns for identity, diagnostic settings, role assignments, locks and private endpoints — primarily through the Azure/avm-utl-interfaces/azure utility module — which simplifies authoring, review and consumer experience.

What changed recently?