| name | avm-tf-migration |
| description | Use for AVM Terraform AzureRM-to-AzAPI migrations, state preservation, moved blocks, provider state moves, submodule extraction, upgrade tests, and post-migration specification compliance. |
AVM Terraform Migration
An AzureRM-to-AzAPI migration is complete only when the implementation satisfies the current AVM specifications and existing consumers have a documented, tested state path.
Migration guidance applies to existing modules only. AzureRM may be read, analyzed, and referenced as source input being migrated, including legacy azurerm_* state addresses. Generated target code uses AzAPI for every control-plane and supported Azure operation.
The target rule includes implementation, submodules, upgrade examples, E2E configurations, Terraform tests, fixtures, setup or teardown Terraform, documentation examples, and generated snippets. Supporting control-plane resources use AzAPI, and each standalone target Terraform root includes Azure/azapi in required_providers. Retain an azurerm_* resource or data-source block only when that block independently implements one specific unsupported data-plane/non-ARM operation. Document the exact block and why AzAPI cannot implement it with an upstream AzAPI issue or pull request, and replace the block when support ships. One valid block does not authorize another.
Read TFFR3-TFFR8, TFRMFR1, TFRMNFR1, TFRMNFR2, TFNFR38, and TFNFR39 through https://azure.github.io/Azure-Verified-Modules/llms.txt before choosing the migration shape.
Separate two changes
Treat these as different graph migrations:
- Provider migration in place:
azurerm_* to an AzAPI resource at the same module/cardinality boundary.
- Composition migration: moving a resource across a module boundary, such as extracting a root collection into
module.child[each.key].azapi_resource.this.
