How to use Azure aztfexport 101 Guide

1. Introduction: The Brownfield Challenge

So, you've got a sprawling Azure estate. Some of it was clicked together in the portal, other parts came from ARM templates, and maybe a few scripts are holding things together. Now, the directive is clear: "Get this all into Terraform." That's a daunting prospect. Manually inventorying everything, writing HCL from scratch, and importing state? It's a mountain of work. This is where Microsoft's aztfexport tool steps in, promising to give you a running start. But is it a complete solution, or just the first step in a longer journey?

2. What Exactly is aztfexport?

Azure Export for Terraform (aztfexport), formerly aztfy, is Microsoft's open-source command-line tool designed to scan your existing Azure resources and spit out Terraform HCL code and a state file. The main idea is to get your current Azure setup reflected in Terraform code so that an initial terraform plan shows no changes. It’s Microsoft's nod to the reality that many folks are looking to adopt Terraform for established "brownfield" environments.

It supports both the common azurerm provider and the azapi provider, which is handy for newer Azure services or preview features not yet fully baked into azurerm.

3. Under the Hood: How aztfexport Works

aztfexport isn't just one monolithic thing. It uses a couple of internal Go programs and libraries:

• aztft: This figures out the Terraform resource type for a given Azure resource ID.
• terraform import: The standard Terraform command is used under the covers to pull the resource's current state into the Terraform state file.
• tfadd: After importing, this component reads that state information and generates the HCL code.

You can run it interactively, where it lists resources and you can pick and choose, or non-interactively, which is better for scripting.

4. Getting Your Hands Dirty: Installation and Basic Usage

Before you start, you'll need Terraform (0.12+) and the Azure CLI installed and configured.

Installation Examples

Installation varies by OS:

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

You can export a single resource, a whole resource group, or use an Azure Resource Graph query:

Exporting with an Azure Resource Graph Query:

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

Exporting a Resource Group:

aztfexport resource-group myRG

(Often good to use with -n for non-interactive mode if the RG is large)

Exporting a Single Resource:

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

The tool generates .tf files and a terraform.tfstate file. It also creates a JSON mapping file (aztfexportResourceMapping.json), which logs what it did and can be used to guide subsequent exports.

5. The Bright Side: Why aztfexport is Useful

Let's be clear, aztfexport does offer some real benefits:

• IaC Adoption Accelerator: It massively cuts down the initial donkey work of getting existing stuff into Terraform. This is its biggest win.
• Migration Aid: Moving resources or understanding legacy setups for a migration? Exporting the config gives you a detailed snapshot.
• Auditing & Documentation: The generated HCL can act as a form of "living documentation," helping to spot configuration drift.
• Learning Tool: New to Terraform for Azure? Exporting resources you know can be a decent way to see how they're defined in HCL.

6. The Reality Check: Limitations and the Work Ahead

And here's where we need to set expectations. aztfexport is a starting point, not a magic wand. Microsoft is pretty upfront that the generated code is not meant to be fully reproducible from scratch. The goal is "no diffs" against existing infrastructure, not perfect, production-ready code for new deployments.

Why?

• Some settings aren't readable via ARM APIs or supported by the Terraform providers.
• It might not grab every nuanced configuration or default setting.
• Dependencies are often explicit (depends_on) rather than the preferred implicit references.
• Naming can be generic (hello, res-1), and Azure IDs might be hardcoded.

This means the output always needs significant manual review and refactoring. You'll be:

• Renaming resources.
• Replacing static IDs with dynamic references.
• Adding variables for parameterization.
• Modularizing the code.
• Handling sensitive data properly (it might export secrets if they're in the config!).
• Ensuring everything meets your company's standards for security and code quality.

This refactoring isn't trivial. It requires solid Terraform knowledge. And this is where the utility of a simple export tool ends, and the need for a more structured approach to IaC management becomes apparent. While aztfexport can get the raw code onto your machine, organizing it, ensuring it adheres to policies, managing its state collaboratively, and integrating it into CI/CD pipelines across multiple teams and environments is a whole different ballgame. This is precisely where comprehensive IaC management platforms add critical value, by providing the frameworks for governance, collaboration, and operationalizing this newly-exported code.

7. aztfexport in Context: Compared to Other Tools

How does aztfexport stack up?

aztfexport vs. Native terraform import

The old terraform import CLI command just pulls state; you have to write all the HCL manually. aztfexport is a big step up because it generates the HCL too. Newer Terraform versions (1.5+) have "import blocks" that can generate config, which is an improvement, but aztfexport still offers a more guided experience for bulk Azure discovery.

Here’s a quick comparison:

Compared to a multi-cloud tool like Terraformer, aztfexport's Azure-only focus, being a Microsoft product, generally means better, more up-to-date support for Azure specifics. Terraformer's Azure provider has been noted to sometimes lag.

8. The Big Picture: From Export to Enterprise IaC

aztfexport is a genuinely useful tool for that initial, painful step of getting existing Azure resources into Terraform. It automates a tedious process and can save a lot of upfront time.

But, and it's a big but, the journey doesn't end there. The output is a draft, a starting point. Turning that draft into robust, maintainable, secure, and scalable Infrastructure as Code requires significant expertise, effort, and the right processes. This is where the limitations of a simple export tool become clear. Managing code at scale, ensuring compliance, handling state securely across teams, providing self-service capabilities, and integrating with broader DevOps toolchains are challenges that aztfexport alone doesn't solve.

Organizations serious about IaC need to think beyond just code generation. They need to consider the entire lifecycle of that code: how it's governed, how it's deployed, how it's versioned, and how teams collaborate on it. This is where platforms designed for Terraform at scale come into their own, providing the structure and control that transforms exported code into truly managed infrastructure. aztfexport can get you to the starting line, but a comprehensive IaC platform helps you run the marathon.