Different ways to migrate Terraform State

Background

Terraform is a well-known Infrastructure as Code (IaC) tool that helps in maintaining the state of solution infrastructure and tracks the changes to them over time.

However, at times, there can be needs to migrate the Terraform state from one backend to another. This could be due to cost cutting measures, easier management, better tooling, or a multitude of reasons.

In this segment, I will demo 3 different ways to migrate Terraform states from one backend to another with examples.

Prerequisites

Before diving into the details of Terraform state migration, please ensure that you have the necessary setup in place:

• Terraform installed on local machine
• Access to two different Terraform backends for migration (e.g., AWS S3, Azure Blob Storage, GCP Storage, etc.)
• Knowledge of the existing Terraform state backend configuration

Migrating the Terraform State

I have played with about 3 ways to migrate Terraform state from one backend to another.

Method 1: Using Terraform Commands

The first method to migrate the Terraform state is simply by using Terraform commands.

We can follow the below steps to migrate the Terraform state:

1. Initialize the new backend configuration using the terraform init command.

terraform init -backend-config="access_key=ACCESS_KEY" \
-backend-config="secret_key=SECRET_KEY" \
-backend-config="bucket=wahab-state-bucket" \
-backend-config="region=us-east-1"

Here, we are initializing the new backend with the AWS S3 bucket wahab-state-bucket, located in the us-east-1 region. We are also passing the access key and secret key as backend configuration parameters.

2. Modify the backend block in the terraform.tf file to point to the new backend configuration.

terraform {
  backend "s3" {
    bucket = "wahab-state-bucket"
    key    = "terraform.tfstate"
    region = "us-east-1"
    access_key = "ACCESS_KEY"
    secret_key = "SECRET_KEY"
  }
}

Here, we are modifying the backend block to point to the new backend configuration that we initialized in step 1.

3. Run the terraform plan command to verify that the migration was successful.

terraform plan

4. If the plan looks good, apply the changes by running the terraform apply command.

terraform apply

This will migrate the Terraform state from the old backend to the new S3 backend.

Method 2: Using the terraform state Command

The second method to migrate the Terraform state is by using the terraform state command.

We can follow the below steps to migrate the Terraform state:

1. Export the current Terraform state from the old backend using the terraform state pull command.

terraform state pull > terraform.tfstate

This will export the current Terraform state to a local file named terraform.tfstate.

2. Initialize the new backend configuration using the terraform init command.

terraform init -backend-config="access_key=ACCESS_KEY" \
-backend-config="secret_key=SECRET_KEY" \
-backend-config="bucket=wahab-state-bucket" \
-backend-config="region=us-east-1"

Here, we are initializing the new backend with the same S3 bucket wahab-state-bucket, located in the us-east-1 region.

3. Import the Terraform state to the new backend using the terraform state push command.

terraform state push terraform.tfstate

This will import the Terraform state from the local file terraform.tfstate to the new backend.

4. Modify the backend block in the terraform.tf file to point to the new backend configuration.

terraform {
  backend "s3" {
    bucket = "wahab-state-bucket"
    key    = "terraform.tfstate"
    region = "us-east-1"
    access_key = "ACCESS_KEY"
    secret_key = "SECRET_KEY"
  }
}

Here, same, we are modifying the backend block to point to the new backend configuration that we initialized in step 2.

5. Run the terraform plan command to verify that the migration was successful.

terraform plan

6. If the plan looks good, apply the changes by running the terraform apply command.

terraform apply

This will also migrate the Terraform state from the old backend to the new S3 backend.

Method 3: Using a Migration Tool

The third method to migrate the Terraform state is by using a migration tool.

A migration tool like terragrunt can help automate the migration process. We can follow the below steps to migrate the Terraform state:

1. Install terragrunt on the local machine. (I have a Mac, so using Homebrew to install terragrunt)

brew install terragrunt

2. Create a terragrunt.hcl file with the following configuration:

remote_state {
  backend = "s3"
  config = {
    bucket         = "wahab-state-bucket"
    key            = "terraform.tfstate"
    region         = "us-east-1"
    access_key     = "ACCESS_KEY"
    secret_key     = "SECRET_KEY"
    dynamodb_table = "terraform-lock"
  }
}

include {
  path = "${find_in_parent_folders()}"
}

Here, we are specifying the new backend configuration in the remote_state block. We are also specifying the location of the Terraform configuration files in the include block.

3. Run the terragrunt state pull command to export the Terraform state from the old backend.

terragrunt state pull > terraform.tfstate

This will export the Terraform state to a local file named terraform.tfstate.

4. Run the terragrunt state push command to import the Terraform state to the new backend.

terragrunt state push terraform.tfstate

This will import the Terraform state from the local file terraform.tfstate to the new backend.

5. Verify the migration by running the terragrunt plan command.

terragrunt plan

6. If the plan looks good, apply the changes by running the terragrunt apply command.

terragrunt apply

This will also migrate the Terraform state from the old backend to the new S3 backend.

Closing thoughts 👏

Thanks for following along. Feel free to add questions / inputs below in the comments.

These are the 3 methods that I’ve played with to migrate states across backends. Any can be used, in my personal opinion, all depends on what you are comfortable with using.