Terraform Resource Migration

tfmigrate is only installed by default in the GiLab Pipeline

The GitLab pipeline integrates tfmigrate. It can handle automatically terraform state mv for renaming terraform resources when using remote state.

Why do we need this? Please see official documentation

Workflow

  1. Push your tf renamed resources and create a merge request (MR). Make sure introduced changes do not introduce a new tf resource, nor changes arguments (for every planned ADD there should be a DELETE and vice-versa). Other type of planned changes tfmigrate will output an error later on.

  2. Check pipeline output. Verify the terraform plan. If previous statement is not respected, remove whatever extra bit you added, and go back to step 1.

  3. Create tfmigrate.hcl file and describe those operations. Each MOVE operation should correspond to a ADD and DELETE planned operation. See Example

  4. Commit and push file into MR, check pipeline (tfmigrate plan output).

  5. Merge MR (this corresponds to a tfmigrate apply, equivalent to moving the states).

  6. Delete tfmigrate.hcl file, push and merge.

  7. Proceed with any other terraform code modification.

Example

migration "state" "test" {
    actions = [
        "mv azurerm_key_vault.bar azurerm_key_vault.bar2", (1)
        "mv module.my_old_module.azurerm_key_vault.vault_test module.my_new_module.azurerm_key_vault.this", (2)
    ]
}
1 updates resource name
2 moves a resource from my_old_module to my_new_module, and renames it from vault_test to this