How to merge Terraform state files

3 min readAug 31, 2024

## Overview

Merging Terraform state files can be a critical task when you’re consolidating resources from different environments or projects. In this guide, we will walk through the steps to merge Terraform state files from a source and a destination, ensuring that your infrastructure remains consistent and manageable. By the end of this article, you’ll have a clear understanding of how to perform this operation without losing any resources.

## Steps

### Step 1: Pull the State Files

First, you’ll need to pull the state files from both the source and the destination. Run the following commands in your terminal:

# From the source
terraform state pull > source.tfstate
# From the destination
terraform state pull > destination.tfstate

### Step 2: Create a New Directory for Merging

Next, create a new directory to hold the state files:

mkdir merge-state
mv /path/to/source.tfstate merge-state
mv /path/to/destination.tfstate merge-state
cd merge-state

### Step 3: List Resources

Now, generate a list of resources from both state files:

terraform state list -state=destination.tfstate > destination-resources.txt
terraform state list -state=source.tfstate > source-resources.txt

You can check the number of resources in each file:

wc -l source-resources.txt 
wc -l destination-resources.txt

### Step 4: Move Resources

Before moving resources, let’s handle any potential issues with double quotes in the resource names. Use the following command to move resources from the source to the destination state file:

while IFS= read -r resource; do
 terraform state mv -state=source.tfstate -state-out=destination.tfstate "$resource" "$resource"
done < source-resources.txt

After executing the above command, confirm that the resources have been moved:

terraform state list -state=source.tfstate | wc -l
terraform state list -state=destination.tfstate | wc -l

### Step 5: Move Terraform Code

Once the state files are merged, you need to move the corresponding Terraform code from the source to the destination directory.

### Step 6: Update the Destination State File

Navigate to the directory containing your destination Terraform code and copy the updated state file:

cp /path/merge-state/destination.tfstate destination-after.tfstate

Next, change the backend configuration from remote to local:

- backend "s3" {
- bucket = "your-terraform"
- key = "aws/naka/terraform.tfstate"
- }
+ backend "local" {
+ path = "destination-after.tfstate"
+ }

Reinitialize your Terraform configuration:

terraform init -reconfigure

### Step 7: Verify the Changes

Run a plan to verify that the state and configuration are in sync:

terraform plan

If everything is correct, you should see:

No changes. Your infrastructure matches the configuration.

### Step 8: Restore Remote State

After confirming the merge is successful, revert the backend configuration back to the original remote backend settings:

+ backend “s3” {
+ bucket = “your-terraform”
+ key = “aws/naka/terraform.tfstate”
+ }
- backend “local” {
- path = “destination-after.tfstate”
- }

Run terraform init -migrate-state to migrate the local state back to the remote backend:

terraform init -migrate-state

When prompted, confirm the overwriting of the existing state:

Do you want to overwrite the state in the new backend with the previous state?
Enter “yes” to copy and “no” to start with the existing state in the newly configured “s3” backend.

### Step 9: Final Verification

Finally, run `terraform plan` one last time to ensure everything is in order:

No changes. Your infrastructure matches the configuration.

Congratulations! You have successfully merged the Terraform state files.

## Summary

Merging Terraform state files is a straightforward process if you follow the right steps. By pulling the state files, moving resources, and managing the backend configuration, you can maintain your infrastructure cleanly and efficiently. Remember to always verify your changes and be cautious of any potential issues during the merging process. If anything goes wrong, you can always revert to the previous state using your backup files. Happy coding!