AzureFeeds

We are very pleased to announce that migration guidance and tooling to aid Terraform import is now moving from public preview to being generally available.

Where to find it

Head over to aka.ms/alz/tf/migrate to read our guidance and find our tooling.

What does it do

The migration guidance talks you through the procedure to migrate Terraform state from the classic CAF Enterprise Scale module to the Terraform Azure Verified Modules for Platform Landing Zone (ALZ) modules. The guidance and tooling helps you generate a set of Terraform import blocks to import the state of your existing platform landing zones into the Azure Verified Modules (AVM).

Once those blocks have been generated, you can raise a pull request, test and merge then apply with your continuous delivery tool to import the state. From there forwards, you will be managing the platform landing zone with the AVM.

How does it work

The migration tool aids in mapping your deployed Microsoft Azure resources against the Azure Verified Modules. It maps on name or other available attributes.

The tool follows a 3 stage process:

• Setup


• Resource Mapping


• Resource Attribute Mapping

Setup

This stage involves you configuring the target Terraform module by using the ALZ IaC Accelerator or composing your own module for advanced use cases. You will also need to identify your existing management group hierarchy and platform subscriptions in this stage.

Resource Mapping

During this stage you will run the migration tool. The tool will attempt to match all resources in the target subscriptions and / or management groups against the Azure Verified Module planned resources. For anything it can’t match on, it will provide details in a file called issues.csv.

You’ll review issues.csv and correct any resource names in the target module to ensure they match your existing resource names. You’ll then run the tool again and repeat until you have matched everything you can. We provide example tfvars files and lib folder to make this easier, they are commented with things you’ll likely need to change.

Once you have updated all the names you can, if you still have any issues left in `issues.csv`, you’ll need to specify what you want to do with them. You can either:

• Ignore them


• Destroy and Recreate them


• Destroy them

You’ll add the action against each row in the CSV and then save the CSV file as `resolved-issues.csv` ready for the next stage.

Resource Attribute Mapping

Now you’ve mapped the resources themselves, you’ll need to check that the attributes of the resources also match your existing configuration where they need to. To help with this you’ll run the tool again, this time supplying your `resolved-issues.csv` as an input. This will prompt the tool to generate the Terraform import blocks and run a Terraform plan. The tool outputs a simplified plan file that only includes the changes you need to care about, namely `update` and `destroy and recreate`. 

You’ll review the simplified plan file and determine if anything in there requires an update to your target module. If it does, you can update it and re-run the tool. You can repeat this until all unwanted changes are handled.

You’ll run the tool one last time to generate the final set of imports and now you are ready to apply the Terraform via your standard CI / CD process.

Limitations

At this time our guidance only support resources that can be deployed by the classic CAF Enterprise Scale module. The tooling can technically support importing any resources, but we don’t provide support or guidance for that scenario.

The documentation of the tool for advanced scenarios is currently limited and we assume usage for this use case only at this time.

Tooling

This migration guidance uses a generic tool call Terraform State Importer . This tool can be used to migrate state for any Azure Resource Manager Terraform resources to a new Terraform module. We provide specific configuration files and settings for this use case, but you could modify them for more advanced scenarios.

The tool does not look at any existing module or Terraform state file, it directly queries Azure using KQL queries to identify your deployed resources, as such it could also be used to import resources deployed via ClickOps, ARM or Bicep too.

Thanks

Thanks to the following people for making this happen:

• Matt White and Jack Tracey for technical guidance and validation


• Paul Grimley and Charlie Grabiaud for keeping it on track


• Haflidi Fridthjofsson (Microsoft) and Aidan Hughes (Servent) for the comprehensive and very valuable testing and feedback