Edit

Migration paths between Azure, AzureRM, and AzAPI Terraform providers

Terraform enables the definition, preview, and deployment of cloud infrastructure. Using Terraform, you create configuration files using HCL syntax. The HCL syntax allows you to specify the cloud provider - such as Azure - and the elements that make up your cloud infrastructure. After you create your configuration files, you create an execution plan that allows you to preview your infrastructure changes before they're deployed. Once you verify the changes, you apply the execution plan to deploy the infrastructure.

Several tools and workflows exist for moving between Azure infrastructure and Terraform, or between the AzureRM and AzAPI Terraform providers. The right path depends on your starting point and goal.

Key tools include aztfexport (exports existing Azure resources into Terraform configuration and state) and aztfmigrate (converts Terraform configurations between the AzureRM and AzAPI providers).

Use the following table to identify which section applies to your scenario:

Starting point Goal Recommended path
Existing Azure resources (not yet in Terraform) Bring under Terraform management Export with aztfexport
ARM template or Azure portal resource JSON Author new AzAPI Terraform resources Paste as AzAPI in VS Code
Existing Terraform config using AzAPI Migrate to AzureRM provider Migrate with aztfmigrate
Existing Terraform config using AzureRM Migrate to AzAPI provider Migrate with aztfmigrate or the VS Code extension

For guidance on which provider should be primary for new projects, see Choose between AzureRM and AzAPI Terraform providers.

Export existing Azure resources to Terraform

Azure Export for Terraform (aztfexport) brings existing Azure resources under Terraform management by generating HCL configuration and Terraform state. It supports both AzureRM and AzAPI as output targets.

Use this path when: You have existing Azure resources that aren't yet managed by Terraform and want to import them.

Export methods

Choose the export method that best fits your workflow:

For detailed quickstarts and advanced scenarios, see:

Export resources in the Azure portal

The Azure portal integration allows you to export resources without installing additional tools:

  1. Navigate to the resource in the Azure portal.
  2. Locate the Export to Terraform option (exact location depends on resource type).
  3. Follow the prompts to select output provider (AzureRM or AzAPI) and export scope.
  4. Download the generated Terraform configuration and state file.
  5. Review the output and run terraform plan to confirm no drift.

For step-by-step guidance, see Export a resource in the Azure portal.

Author AzAPI resources from ARM JSON

If you have an ARM template, Azure portal resource definition, or raw REST API response and want to generate a corresponding azapi_resource block, the Microsoft Terraform VS Code extension can convert it automatically.

Use this path when: You're authoring new AzAPI resources and have an existing JSON definition (ARM template, portal export, API response) as a starting point.

The extension converts the JSON properties to the body attribute format and infers the type and api-version. For detailed steps and examples, see Paste ARM JSON as AzAPI configuration in the VS Code extension guide.

Note

This feature works best for single resource objects. Full ARM templates with multiple resources, parameters, and variables might require manual cleanup after conversion.

Migrate AzAPI resources to AzureRM with aztfmigrate

aztfmigrate migrates existing azapi_resource blocks in a Terraform configuration to their equivalent azurerm_* resource types. It updates both the HCL (HashiCorp Configuration Language) files and the Terraform state file without re-creating the underlying Azure resources.

Use this path when: Your team manages resources with AzAPI and a resource you're using has since been added to the AzureRM provider with full support, and you want to consolidate onto AzureRM.

Prerequisites

  • An existing Terraform configuration with azapi_resource blocks you want to migrate.
  • The aztfmigrate binary installed and in your PATH. Download from the aztfmigrate releases page.
  • Azure subscription: If you don't have an Azure subscription, create a free account before you begin.

Plan the migration

  1. Navigate to the directory containing your Terraform configuration.

  2. Authenticate to Azure:

    az login
az account set --subscription <subscription_id>

  3. Run aztfmigrate plan to identify which resources can be migrated to AzureRM:

    aztfmigrate plan

    The output lists each azapi_resource block, indicating whether it maps to a supported AzureRM resource type. Resources using preview API versions or resource types not yet in AzureRM are listed as not migratable and remain as azapi_resource blocks.

  4. Review the plan output and confirm the mappings are correct before proceeding.

Perform the migration

  1. Run aztfmigrate migrate to apply the changes:

    aztfmigrate migrate

    aztfmigrate:

    • Replaces azapi_resource blocks in your .tf files with the equivalent azurerm_* blocks.
    • Updates the state file to reflect the new resource addresses and schema.

  2. Initialize Terraform to download any updated provider versions:

    Run terraform init to initialize the Terraform deployment. This command downloads the Azure provider required to manage your Azure resources.

    terraform init -upgrade

    Key points:

    • The -upgrade parameter upgrades the necessary provider plugins to the newest version that complies with the configuration's version constraints.

  3. Run terraform plan to validate that configuration and state align with the deployed infrastructure:

    terraform plan

    The plan should show no changes. If differences appear, review the diff and adjust the migrated configuration before applying.

Post-migration cleanup

After confirming a clean plan:

  • Remove the azapi provider from required_providers if no AzAPI resource blocks remain.
  • Update any output or locals blocks that reference AzAPI-specific attributes.
  • Run terraform apply to apply any legitimate drift, such as normalized defaults introduced by AzureRM.

Migrate AzureRM resources to AzAPI

To convert an existing AzureRM configuration to use AzAPI, use the Microsoft Terraform VS Code extension, which includes tooling to generate AzAPI equivalents for azurerm_* resource blocks.

Use this path when: You're converting a Terraform module or configuration from AzureRM to AzAPI and want editor assistance with the conversion.

For step-by-step instructions, code actions, and state migration guidance, see the VS Code extension guide.

Important

The VS Code extension assists with HCL authoring only—it does not update the Terraform state file. Replacing azurerm_* blocks with azapi_resource blocks without updating state causes Terraform to treat the resources as deleted and re-create them.

After converting HCL, use terraform state mv for each resource or re-import using the import block. Run terraform plan after each state change to confirm no unintended re-creation occurs.

When not to migrate

Consider keeping resources where they are when:

  • The resource is in preview or uses a preview API version not yet in AzureRM—keep it in AzAPI.
  • Your team uses AzAPI as its primary provider—add new AzureRM-only resources with AzAPI rather than introducing a second primary provider.
  • The AzureRM representation introduces unwanted plan drift from normalized defaults—evaluate the impact before migrating.
  • State migration complexity is high—for large configurations, assess whether the operational risk of state manipulation outweighs the benefit of switching providers.

Next steps

Choose between AzureRM and AzAPI Terraform providers

Azure Export for Terraform overview

Terraform AzAPI provider overview

  • Last updated on