migrate

Usage

Migrate OpenTofu/Terraform state from one unit to another.

Examples

Migrate backend state from `unit` to `unit-renamed`.

backend migrate old-unit-name new-unit-name

Force state migration, even if the bucket doesn't have versioning enabled.

backend migrate --force old-unit-name new-unit-name

This command will migrate the OpenTofu/Terraform state backend from one unit to another.

You will typically want to use this command if you are using a key attribute for your remote_state block that uses the relative_path_to_include function, and you want to rename the unit.

For example, given the following filesystem structure:

• Directoryold-unit-name

  • terragrunt.hcl
• root.hcl

root.hcl

remote_state {
  backend = "s3"
  generate = {
    path      = "backend.tf"
    if_exists = "overwrite"
  }
  config = {
    bucket         = "my-tofu-state"
    key            = "${path_relative_to_include()}/tofu.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "my-lock-table"
  }
}

old-unit-name/terragrunt.hcl

include "root" {
  path = find_in_parent_folders("root.hcl")
}

You couldn’t simply rename the old-unit-name directory to new-unit-name and run terragrunt apply in new-unit-name, because the change in the evaluated value for path_relative_to_include() would result in a new state key for the new-unit-name unit.

Instead, you can use the backend migrate command to migrate the backend state from the old-unit-name unit to the new-unit-name unit.

cp -R old-unit-name new-unit-name
terragrunt backend migrate old-unit-name new-unit-name
rm -rf old-unit-name

This will migrate the backend state from the old-unit-name unit to the new-unit-name unit, and then delete the old-unit-name unit.

Terragrunt performs migrations in one of two ways, depending on the level of support for the backends being migrated, and the state of configuration between the two units.

1. If the backend source for both the source and destination units are the same (both are S3 or GCS), Terragrunt will use the AWS/GCP SDK to move state between the two units transparently without interacting with OpenTofu/Terraform. This is the preferred method, when possible.
2. If either backend source isn’t supported by Terragrunt, or the state of configuration between the two units is different, Terragrunt will instead use the OpenTofu/Terraform CLI to move the state between the two units. This is the fallback method, and will generally be slower. Terragrunt also won’t be able to delete the existing state from the source unit in this case, so you’ll need to handle that yourself.

Flags

--config

Path to the Terragrunt configuration file to use to migrate the resources. Note that this path is relative to the directory of each of the source and destination units, not the current working directory.

Type: string

Environment Variables:

• TG_CONFIG

--download-dir

Path to download OpenTofu/Terraform modules into. The default is `.terragrunt-cache`. Note that this path is relative to the directory of each of the source and destination units, not the current working directory.

Type: string

Environment Variables:

• TG_DOWNLOAD_DIR

--force

When this flag is set, Terragrunt will force the migration of the backend state, even if the bucket containing it has versioning disabled.

Danger

This flag is dangerous and should be used with caution.

Gruntwork recommends always enabling versioning on your backend state resources. Migrating backend state without versioning enabled can result in irreversible data loss.

Type: bool

Environment Variables:

• TG_FORCE