Avm Tf Azapi

AVM Terraform AzAPI

Read the current TFFR3-TFFR8, TFNFR38, TFRMFR1, TFRMNFR1, and TFRMNFR2 pages through https://azure.github.io/Azure-Verified-Modules/llms.txt before implementing or reviewing an AzAPI resource.

Provider requirements

Every new AVM Terraform module repository that deploys Azure resources MUST use AzAPI for every control-plane resource and every supported direct Azure operation. Do not declare or configure hashicorp/azurerm, and do not create any azurerm_* resource or data source for convenience or ordinary supporting infrastructure.

This managed-authoring prohibition applies to the root implementation, submodules, examples, E2E configurations, Terraform tests, fixtures, setup or teardown Terraform, migration examples, documentation examples, and generated snippets. When supporting Terraform needs a direct Azure resource that the module under test does not supply, use an AzAPI resource, data source, or action.

TFFR3 requires:

terraform {
  required_providers {
    azapi = {
      source  = "Azure/azapi"
      version = "~> 2.12"
    }
  }
}

~> 2.12 means >= 2.12, < 3.0. The 2.12 floor is required for ignore_body_changes.

Every standalone Terraform root that performs a direct Azure operation MUST include Azure/azapi in required_providers. Use azapi_resource, azapi_data_plane_resource, azapi_resource_action, azapi_update_resource, or an AzAPI data source as appropriate. Do not start a new module from an AzureRM implementation and treat migration as future work.

hashicorp/azurerm ~> 4.0 is permitted only when required for a data-plane or other non-ARM operation that genuinely cannot be implemented with those AzAPI resource forms. Each azurerm_* resource or data-source block independently scopes to one specific unsupported operation, documents the exact block and why AzAPI cannot implement it with an upstream AzAPI issue or pull request, and is replaced when support ships. Prefer an AVM TFLint override file, but use a justified line-level annotation when it avoids suppressing unrelated findings in the same scope. One valid block does not authorize another. Do not use the exception for any control-plane resource. Follow avm-tf-tflint.

Complete resource pattern

For Microsoft.Example/widgets, the deterministic TFFR6 key is example_widgets:

resource "azapi_resource" "this" {
  type      = var.resource_types.example_widgets
  name      = var.name
  parent_id = var.parent_id
  location  = var.location

  body = {
    properties = {
      skuName = var.sku_name
    }
  }

  ignore_body_changes = length(var.ignore_body_changes.example_widgets) > 0 ? var.ignore_body_changes.example_widgets : null
  replace_triggers_refs = [
    "properties.skuName",
  ]
  response_export_values = [
    "properties.provisioningState",
  ]
  retry = var.retry

  dynamic "timeouts" {
    for_each = var.timeouts == null ? [] : [var.timeouts]
    content {
      create = timeouts.value.create
      read   = timeouts.value.read
      update = timeouts.value.update
      delete = timeouts.value.delete
    }
  }
}

The primary resource label is this. Satellite resources such as locks, role assignments, and diagnostic settings use descriptive labels.

Required AzAPI arguments

• type: always read from var.resource_types.<deterministic_key>.
• response_export_values: present on every resource, even when empty.
• replace_triggers_refs: omit when no body paths require replacement. When present, use a non-empty static list of unique, valid JMESPath body paths; do not include name or location.
• retry: assigned directly from var.retry.
• timeouts: emitted with a dynamic block from var.timeouts.
• ignore_body_changes: read from the field for this specific resource and collapse [] to null.
• tags: set exactly to var.tags when the current AVM ruleset capability snapshot marks the resource type as taggable; omit it for unsupported types.

The same requirements apply to equivalent AzAPI resource types, not only azapi_resource.

resource_types

Drop Microsoft., lowercase the provider token without splitting internal capitals, convert each resource path segment to snake case, and join the tokens with underscores:

variable "resource_types" {
  type = object({
    example_widgets     = optional(string, "Microsoft.Example/widgets@2024-01-01")
    authorization_locks = optional(string, "Microsoft.Authorization/locks@2020-05-01")

    example_widgets_parts = optional(object({
      example_widgets_parts = optional(string)
    }), {})
  })
  default  = {}
  nullable = false
  description = <<DESCRIPTION
AzAPI resource types and API versions used by the module.

- `example_widgets` - Resource type and API version for the widget.
- `authorization_locks` - Resource type and API version for locks.
- `example_widgets_parts` - Resource-type overrides passed to the part submodule.
- `example_widgets_parts.example_widgets_parts` - Resource type and API-version override for parts.
DESCRIPTION
}

Each module owns the stable API-version defaults for resources it declares. A parent's nested submodule slot mirrors the child variable but does not repeat the child's string defaults. Document every owned-resource field and every nested submodule field in the variable description.

ignore_body_changes

The shape uses the same keys and module tree as resource_types, but each owned resource has a list of body paths:

variable "ignore_body_changes" {
  type = object({
    example_widgets = optional(list(string), [])

    example_widgets_parts = optional(object({
      example_widgets_parts = optional(list(string), [])
    }), {})
  })
  default  = {}
  nullable = false
  description = <<DESCRIPTION
Body-relative paths to ignore for each AzAPI resource. Paths use dot notation.
Changes take effect only after apply. Ignored configuration is not sent to Azure
until the path is removed.

- `example_widgets` - Paths ignored on the widget resource.
- `example_widgets_parts` - Paths passed to the part submodule.
- `example_widgets_parts.example_widgets_parts` - Paths ignored on part resources.
DESCRIPTION
}

Rules:

• declare one optional(list(string), []) field for each AzAPI resource owned by the module;
• declare one nested object matching each instantiated submodule's full shape;
• pass the nested slot to that submodule unchanged;
• use non-empty body-relative dot paths such as tags or properties.sku.name;
• do not address individual list indices; ignore the whole list property;
• collapse empty lists to null;
• do not raise the Terraform version floor solely for this feature; and
• document that provider-private changes take effect after apply.

Non-empty values require Terraform 1.11 or later. Prefer static lifecycle.ignore_changes when the ignored references are compile-time static. Static lifecycle references are unquoted, for example ignore_changes = [tags].