From c2c6352dac0708aed99a75fbdc7fe9fce66c05c0 Mon Sep 17 00:00:00 2001 From: Heng Lu <79895375+ms-henglu@users.noreply.github.com> Date: Wed, 27 Nov 2024 11:20:19 +0800 Subject: [PATCH] add guide for migrating resources to azapi in terraform module (#139) --- CHANGELOG.md | 2 +- docs/migrate_to_azapi_in_module_guide.md | 297 +++++++++++++++++++++++ readme.md | 4 + 3 files changed, 302 insertions(+), 1 deletion(-) create mode 100644 docs/migrate_to_azapi_in_module_guide.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 94c1bf93..5f710b94 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,4 @@ -## v2.1.0 (unreleased) +## v2.1.0 FEATURES: - Support `-var-file` option to specify the path to the terraform variable file. diff --git a/docs/migrate_to_azapi_in_module_guide.md b/docs/migrate_to_azapi_in_module_guide.md new file mode 100644 index 00000000..34e94a3e --- /dev/null +++ b/docs/migrate_to_azapi_in_module_guide.md @@ -0,0 +1,297 @@ +# Guide to migrate AzureRM resources to AzAPi in Module + +## Introduction + +This guide is intended to help you migrate your existing AzureRM resources to AzApi in Terraform Module. + + +## Prerequisites + +- Terraform 1.8.0 or later +- Aztfmigrate 2.1.0 or later + +## Migration Steps + +This guide will walk you through the steps to migrate your existing AzureRM resources to AzApi in Terraform Module. +It will use [terraform-azurerm-avm-ptn-aks-dev](https://github.com/Azure/terraform-azurerm-avm-ptn-aks-dev) as an example. +The target is to migrate the `azurerm_management_lock` to `azapi_resource` in the module. + +### Step 1: Deploy the resources in root module + +The migration flow only works with deployed resources. And it only supports the resources in the root module. + +Please add the necessary terraform code to deploy the resources in the root module. In the `terraform-azurerm-avm-ptn-aks-dev` example, you can add the following code to deploy the `azurerm_management_lock` resource. + +```hcl +// provider.tf + +provider "azurerm" { + features {} + + subscription_id = "00000000-0000-0000-0000-000000000000" +} + +``` + +```hcl +// terraform.tfvars + +location = "eastus" +resource_group_name = "heng-aks" // name of an existing resource group +name = "henglutest" +lock = { // enable the lock + kind = "CanNotDelete" + name = "mylock" +} +``` + +After adding the code, run `terraform init` and `terraform apply` to deploy the resources. + +**Note**: Please use the Azure CLI to authenticate with Azure before running the `terraform` commands. + +### Step 2: Migrate the resources in the module + +Run `aztfmigrate plan -to azapi` to list all resources that can be migrated from `azurerm` provider to `azapi` provider. + +```bash +$ aztfmigrate plan -to azapi + +2024/11/27 09:35:55 [INFO] target provider: azapi +2024/11/27 09:35:55 [INFO] initializing terraform... +2024/11/27 09:35:56 [INFO] running terraform plan... +2024/11/27 09:36:28 [INFO] + +The tool will perform the following actions: + +The following resources will be migrated: + azurerm_management_lock.this will be replaced with azapi_resource.lock_this + azurerm_role_assignment.acr will be replaced with azapi_resource.roleAssignment_acr + azurerm_user_assigned_identity.aks will be replaced with azapi_resource.userAssignedIdentity_aks + azurerm_container_registry.this will be replaced with azapi_resource.registry_this + azurerm_kubernetes_cluster.this will be replaced with azapi_resource.managedCluster_this + +The following resources can't be migrated: + +The following resources will be ignored in migration: + +``` + +Create an ignore file `aztfmigrate.ignore` to include the resources that you don't want to migrate. For this example, you can add the following content to the `aztfmigrate.ignore` file. + +``` +// aztfmigrate.ignore +azurerm_role_assignment.acr +azurerm_user_assigned_identity.aks +azurerm_container_registry.this +azurerm_kubernetes_cluster.this +``` + +Run `aztfmigrate plan -to azapi` again to list the resources that can be migrated. It will ignore the resources listed in the `aztfmigrate.ignore` file. + +```bash +$ aztfmigrate plan -to azapi + +2024/11/27 09:40:59 [INFO] target provider: azapi +2024/11/27 09:40:59 [INFO] initializing terraform... +2024/11/27 09:40:59 [INFO] running terraform plan... +2024/11/27 09:41:25 [INFO] + +The tool will perform the following actions: + +The following resources will be migrated: + azurerm_management_lock.this will be replaced with azapi_resource.lock_this + +The following resources can't be migrated: + +The following resources will be ignored in migration: + azurerm_role_assignment.acr + azurerm_user_assigned_identity.aks + azurerm_container_registry.this + azurerm_kubernetes_cluster.this +``` + +Run `aztfmigrate migrate -to azapi` to migrate the resources from `azurerm` provider to `azapi` provider. + +```bash +$ aztfmigrate migrate -to azapi + +2024/11/27 09:42:14 [INFO] working directory: /Users/luheng/go/src/github.com/Azure/terraform-azurerm-avm-ptn-aks-dev +2024/11/27 09:42:14 [INFO] initializing terraform... +2024/11/27 09:42:14 [INFO] running terraform plan... +2024/11/27 09:42:30 [INFO] + +The tool will perform the following actions: + +The following resources will be migrated: + azurerm_management_lock.this will be replaced with azapi_resource.lock_this + +The following resources can't be migrated: + +The following resources will be ignored in migration: + azurerm_role_assignment.acr + azurerm_user_assigned_identity.aks + azurerm_container_registry.this + azurerm_kubernetes_cluster.this + +2024/11/27 09:42:30 [INFO] generating import config... +2024/11/27 09:42:30 [INFO] migrating resources... +2024/11/27 09:42:30 [INFO] generating new config for resource azurerm_management_lock.this... +2024/11/27 09:42:30 [INFO] generating config... +2024/11/27 09:42:33 [INFO] updating config... +2024/11/27 09:42:33 [INFO] removing azurerm_management_lock.this from config +2024/11/27 09:42:33 [INFO] replacing references with migrated resource... +``` + +Below is the migrated code block. + +```hcl + +# # required AVM resources interfaces +# resource "azurerm_management_lock" "this" { +# count = var.lock != null ? 1 : 0 +# +# lock_level = var.lock.kind +# name = coalesce(var.lock.name, "lock-${var.lock.kind}") +# scope = azurerm_kubernetes_cluster.this.id +# notes = var.lock.kind == "CanNotDelete" ? "Cannot delete the resource or its child resources." : "Cannot delete or modify the resource or its child resources." +# } +moved { + from = azurerm_management_lock.this + to = azapi_resource.lock_this +} + +resource "azapi_resource" "lock_this" { + count = 1 + type = "Microsoft.Authorization/locks@2020-05-01" + parent_id = azurerm_kubernetes_cluster.this.id + name = "mylock" + body = { + properties = { + level = "CanNotDelete" + notes = "Cannot delete the resource or its child resources." + } + } + ignore_casing = false + ignore_missing_property = true + schema_validation_enabled = true +} +``` + +The generated code may not be perfect, you may need to update rest of the code manually. For example, the reference to the original resource block is not updated to the new resource block. You can update the reference manually. + +Now if you run `terraform plan` command, you will see below output: + +```bash + +Terraform will perform the following actions: + + # azurerm_management_lock.this[0] has moved to azapi_resource.lock_this[0] + resource "azapi_resource" "lock_this" { + id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/heng-aks/providers/Microsoft.ContainerService/managedClusters/aks-henglutest/providers/Microsoft.Authorization/locks/mylock" + name = "mylock" + # (7 unchanged attributes hidden) + } + +Plan: 0 to add, 0 to change, 0 to destroy. +``` + +If you want to migrate other resources, you can repeat the above steps after running `terraform apply` to apply the changes. + +### Step 3: Update the migrated code + +The migrated code is using literal values. You need to update the code to use expressions and variables like the original code. + +```hcl + +resource "azapi_resource" "lock_this" { + count = var.lock != null ? 1 : 0 + type = "Microsoft.Authorization/locks@2020-05-01" + parent_id = azurerm_kubernetes_cluster.this.id + name = coalesce(var.lock.name, "lock-${var.lock.kind}") + body = { + properties = { + level = var.lock.kind + notes =var.lock.kind == "CanNotDelete" ? "Cannot delete the resource or its child resources." : "Cannot delete or modify the resource or its child resources." + } + } + ignore_casing = false + ignore_missing_property = true + schema_validation_enabled = true +} +``` + +It is also possible to rename the `azapi_resource` label, for example: + +```hcl + +moved { + from = azurerm_management_lock.this + to = azapi_resource.cluster_lock // previously azapi_resource.lock_this +} + +resource "azapi_resource" "cluster_lock" { // previously azapi_resource.lock_this + ... +} +``` + +After updating the code, if you run `terraform plan` command, you will see below output: + +```bash + +Terraform will perform the following actions: + + # azurerm_management_lock.this[0] has moved to azapi_resource.cluster_lock[0] + resource "azapi_resource" "cluster_lock" { + id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/heng-aks/providers/Microsoft.ContainerService/managedClusters/aks-henglutest/providers/Microsoft.Authorization/locks/mylock" + name = "mylock" + # (7 unchanged attributes hidden) + } + +Plan: 0 to add, 0 to change, 0 to destroy. +``` + +### Step 4: Clean up + +After updating the migrated code, you can destroy the deployed resources by running `terraform destroy` command. + +Then you can remove the original code block from the module. + +```hcl +// main.tf + +// Below code block is the original code, you can remove it after the migration +# resource "azurerm_management_lock" "this" { +# count = var.lock != null ? 1 : 0 +# +# lock_level = var.lock.kind +# name = coalesce(var.lock.name, "lock-${var.lock.kind}") +# scope = azurerm_kubernetes_cluster.this.id +# notes = var.lock.kind == "CanNotDelete" ? "Cannot delete the resource or its child resources." : "Cannot delete or modify the resource or its child resources." +# } +``` + +Also, you can remove the `provider.tf`, `terraform.tfvars` and `aztfmigrate.ignore` files from the module. + +## Frequently Asked Questions + +### Why do I need to deploy the resources in the root module? + +The migration flow generates new azapi resources based on the existing azurerm resources. Currently, the migration flow only supports the resources in the root module and will improve in the future. + + +### Why do I need to authenticate with Azure CLI? + +The migration flow needs to authenticate with Azure to access the existing resources and generate new azapi resource code. The Azure CLI authentication is easy to use in multiple terraform used in the migration flow. It will improve in the future. + +### How long does the migration take? + +The first migration may take a longer time(1~2 minutes, depending on the network speed) because it needs to download the necessary providers. The subsequent migrations will be faster(about 15s). + +### How about migrating multiple resources? + +The migration flow supports migrating multiple resources at the same time. You can select multiple resource blocks and click on the light bulb icon to migrate them. + + +### How about migrating resources from azapi to azurerm? + +The `azurerm` provider doesn't support `moved` block yet. The migration will support migrating resources from `azapi` to `azurerm` in the future. \ No newline at end of file diff --git a/readme.md b/readme.md index cecf4409..abc8f8b5 100644 --- a/readme.md +++ b/readme.md @@ -3,6 +3,10 @@ ## Introduction This tool is used to migrate resources between terraform `azapi` provider and `azurerm` provider. +## Guides + +- [Guide to migrate AzureRM resources to AzAPi in Module](./docs/migrate_to_azapi_in_module_guide.md) + ## Command Usage ```