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].

Parent scope validation

Resource modules accept an existing parent scope through required parent_id:

variable "parent_id" {
  type        = string
  nullable    = false
  description = "The fully-qualified ARM resource ID of the existing resource group into which the widget will be deployed."

  validation {
    condition     = can(provider::azapi::parse_resource_id("Microsoft.Resources/resourceGroups", var.parent_id))
    error_message = "`parent_id` must be a valid resource group resource ID."
  }
}

The expected type is a literal string. Apply the same TFNFR38 pattern to every ARM resource ID input, including optional, collection, and nested values. Do not accept resource_group_name or construct the parent ID inside a resource module.

Polymorphic inputs that legitimately accept multiple unrelated resource types should not be validated against one arbitrary type. For a general polymorphic input, follow the TFNFR38 exception and leave it without resource-type validation. For an extension-resource module's parent_id, follow TFRMFR1 instead: require a non-empty fully-qualified ID beginning with /subscriptions/ or /providers/, and document the exception in the README.

Submodules

ARM subresources are full local submodules. The parent owns cardinality:

module "part" {
  source   = "./modules/part"
  for_each = var.parts

  name                = each.value.name
  parent_id           = azapi_resource.this.id
  resource_types      = var.resource_types.example_widgets_parts
  retry               = var.retry
  timeouts            = var.timeouts
  ignore_body_changes = var.ignore_body_changes.example_widgets_parts
}

The child declares one azapi_resource.this without count or for_each.

Outputs and sensitive data

Export only properties needed by outputs. Prefer discrete computed outputs:

output "resource_id" {
  value       = azapi_resource.this.id
  description = "The resource ID of the deployed widget."
}

output "provisioning_state" {
  value       = azapi_resource.this.output.properties.provisioningState
  description = "The provisioning state returned by Azure."
}

Put secrets in sensitive_body, make secret inputs ephemeral where required by the current specs, and use sensitive_body_version to make changes detectable without persisting secret values.

ARM schema workflow

Use the repository's PowerShell schema helper rather than guessing:

pwsh .github/skills/avm-tf-azapi/scripts/Get-AzureSchema.ps1 versions Microsoft.Example/widgets
pwsh .github/skills/avm-tf-azapi/scripts/Get-AzureSchema.ps1 get Microsoft.Example/widgets 2024-01-01

Include required writable properties in body, exclude read-only properties, export needed read-only values, and put write-only secret properties in sensitive_body. Prefer a stable API version unless the resource or required feature is preview-only.

For Terraform provider schema inspection beyond ARM body schemas, see the tfpluginschema reference.

Migration checks

When moving from AzureRM:

1. preserve state addresses with a valid moved block or documented state migration;
2. verify the plan has zero unintended destroys or replacements;
3. add resource_types, retry, timeouts, and ignore_body_changes;
4. add required response exports and replacement triggers;
5. update outputs from AzureRM attributes to AzAPI output paths;
6. run integration and upgrade-path tests; and
7. run avm pre-commit, commit, then run avm pr-check on the clean worktree.

AzureRM code and azurerm_* addresses are source input for migration only. Do not carry the AzureRM provider, resources, or data sources into generated target implementation, examples, tests, fixtures, setup or teardown Terraform, or documentation snippets unless the target still requires the documented unsupported data-plane/non-ARM operation.