How to use Azure aztfexport

Azure's aztfexport is a utility for bringing existing Azure resources into Terraform management. Many organizations possess large Azure estates deployed over time using a mix of methods, including the Azure portal, ARM templates, and custom scripts. The task of migrating these "brownfield" environments to a unified Terraform workflow is substantial, requiring significant effort to inventory resources, author HCL, and import state.

Microsoft's aztfexport tool is designed to address this initial challenge by automating the export process.

What is Aztfexport?

Azure Export for Terraform (aztfexport), formerly known as aztfy, is an open-source command-line tool from Microsoft. Its purpose is to scan existing Azure resources, generate corresponding Terraform HCL code, and create a state file that maps to the live infrastructure. The objective is for an initial terraform plan to show no drift, confirming the exported code matches the existing resource state.

The tool supports both the azurerm and azapi Terraform providers. Support for the azapi provider is notable as it allows interaction with newer Azure services or preview features that may not yet be fully implemented in the more common azurerm provider.

How Aztfexport Works

The functionality of aztfexport is delivered by a set of underlying components:

• aztft: A Go program that maps an Azure resource ID to its corresponding Terraform resource type.
• terraform import: The standard Terraform command is used to read the resource's current configuration from Azure and save it into the Terraform state file.
• tfadd: Another Go component that reads the data from the state file and generates the associated HCL code.

The tool can be executed in two modes: an interactive mode for selective export and a non-interactive mode suitable for automation.

Installation and Usage

Prerequisites for using aztfexport include Terraform (v0.12+) and the Azure CLI. Both must be installed and configured.

Installation Examples

The tool can be installed via common package managers:

Linux (apt - Debian/Ubuntu):

# Import Microsoft GPG key
curl -sSL https://packages.microsoft.com/keys/microsoft.asc | sudo tee /etc/apt/trusted.gpg.d/microsoft.asc > /dev/null
# Add Microsoft repository (example for Ubuntu 20.04)
sudo apt-add-repository https://packages.microsoft.com/ubuntu/20.04/prod
# Update package list and install aztfexport
sudo apt-get update
sudo apt-get install aztfexport

Linux/macOS (Homebrew):

brew install aztfexport

Windows (winget):

winget install aztfexport

Basic Commands

aztfexport can target resources in several ways:

Exporting with an Azure Resource Graph Query:

aztfexport query "resourceGroup =~ 'myRG' and type =~ 'microsoft.network/virtualnetworks'"

Exporting a Resource Group:

aztfexport resource-group myRG

(The -n flag for non-interactive mode is recommended for large resource groups.)

Exporting a Single Resource:

aztfexport resource /subscriptions/your-sub-id/resourceGroups/myRG/providers/Microsoft.Compute/virtualMachines/myVM

The tool generates .tf files, a terraform.tfstate file, and a JSON mapping file (aztfexportResourceMapping.json) that logs the association between Azure IDs and Terraform resource addresses.

Primary Use Cases for Aztfexport

The tool provides several practical benefits:

• IaC Adoption Acceleration: It automates the initial, time-consuming task of importing existing resources and generating baseline HCL code.
• Migration Support: Exporting configurations provides a detailed snapshot of legacy resources, which can serve as a reference for migrations or re-platforming efforts.
• Configuration Auditing: The generated HCL acts as a point-in-time documentation of resource configurations, useful for identifying configuration drift.
• Learning Aid: For those new to Terraform for Azure, exporting known resources is a practical way to see how they are defined in HCL.

Limitations and Required Post-Export Refactoring

It is important to note that Microsoft states the generated code is not intended to be fully reproducible from scratch. The goal is to match existing infrastructure, not to create a perfect, production-grade template for new deployments.

This is due to several factors:

• Some resource properties are not readable via ARM APIs or are not supported by the Terraform providers.
• Nuanced configurations or default settings applied by Azure may not be captured.
• Dependencies are often generated as explicit depends_on arguments rather than the preferred implicit HCL references.
• Resource names can be generic, and Azure IDs are often hardcoded as static strings.

Consequently, the output of aztfexport requires a mandatory and thorough manual review and refactoring phase. This process involves:

• Renaming logical resources to align with standards.
• Replacing hardcoded IDs with dynamic references.
• Introducing variables for parameterization.
• Organizing the code into logical modules.
• Securing any sensitive data that may have been exported.
• Ensuring the final code complies with organizational security and coding standards.

This refactoring stage is a critical step in transforming the raw export into a maintainable and scalable IaC codebase. It requires a solid understanding of Terraform best practices.

Aztfexport vs Terraform Import

The traditional terraform import command only populates the state file; the user must write all HCL code manually. aztfexport improves upon this by generating the HCL as well. While recent Terraform versions (1.5+) have introduced import blocks that can generate configuration, aztfexport provides a more streamlined workflow for bulk discovery of Azure resources.

Here is a handy table comparing them:

Compared to the multi-cloud tool Terraformer, aztfexport, as a Microsoft product, generally provides more reliable and up-to-date support for Azure-specific resources and services. Terraformer's Azure provider has been noted to lag at times.

More on Terraform import here, and specifically on Terraform import blocks here.

Summary

aztfexport is an effective utility for the first step in a brownfield-to-IaC migration: getting existing Azure resources and their state into a basic Terraform configuration. It successfully automates what would otherwise be a tedious and error-prone manual process.

However, the export is only the beginning. The output is a raw draft that must undergo significant refactoring and enhancement to become robust, maintainable, and secure Infrastructure as Code. An effective adoption strategy must account for this necessary second phase, which includes establishing code standards, modularizing configurations, implementing variables, and integrating the code into a CI/CD pipeline for testing and deployment. While aztfexport provides the initial assets, a disciplined engineering process is required to turn them into a fully managed IaC system.