How to Merge State Files – HashiCorp Help Center

Introduction

This guide provides instructions on how to merge two separate Terraform state files. The process involves moving resources from a source state file into a destination state file using the terraform state mv command. This is useful when consolidating configurations or restructuring your infrastructure management.

Note: Perform all operations using the version of the Terraform CLI that matches the version specified in the configuration for the final, merged state.

Prerequisites

Before you begin, ensure you have the following:

The Terraform CLI installed.
Access to both the source and destination state files.
A complete backup of both original state files to prevent data loss.

Procedure

Follow these steps to merge your state files.

Step 1: Prepare the Environment

To avoid conflicts with existing backend configurations, create a new, empty directory for this operation.

Obtain both state files and place them in the new directory. If your configuration uses a backend, you can use the terraform state pull command to download each state file. Otherwise, download them manually from your backend (e.g., an S3 bucket or HCP Terraform workspace).
```
## Pull the source state file
$ terraform state pull > source.tfstate

## Pull the destination state file
$ terraform state pull > destination.tfstate
```

Step 2: List Resources in Each State

Identify the resources in each state file to plan the move. Use the terraform state list command with the -state flag to target each file.

List resources in the destination state.

$ terraform state list -state=destination.tfstate

List resources in the source state.

$ terraform state list -state=source.tfstate

Note: The -state flag is a legacy option but is necessary when working with multiple local state files in the same directory. For more details, refer to the local backend documentation. If you use PowerShell, omit the equals sign (e.g., terraform state list -state destination.tfstate).

All resource addresses must be unique across both states to ensure all resources are present in the final merged state.

Step 3: Move Resources to the Destination State

For each top-level resource and module in source.tfstate, use the terraform state mv command to move it to destination.tfstate. Resources and modules nested within a top-level module are moved automatically with their parent.

Use the -state flag for the source file and the -state-out flag for the destination file.

## Move a top-level resource
$ terraform state mv \
    -state=source.tfstate \
    -state-out=destination.tfstate \
    aws_instance.foo aws_instance.foo

## Move a top-level module
$ terraform state mv \
    -state=source.tfstate \
    -state-out=destination.tfstate \
    module.bar module.bar

Step 4: Verify the State Files

After moving all top-level items, verify that the source state is empty and the destination state contains all resources.

Confirm the source state is empty.

$ terraform state list -state=source.tfstate
## This command should produce no output.

Confirm all resources are in the destination state.
```
$ terraform state list -state=destination.tfstate
```

Step 5: Update the Serial Number

Open the destination.tfstate file in a text editor and manually increment the "serial" value by 1. This step is critical for backends to recognize the state file as a new version.

Step 6: Upload the Merged State

Upload the modified destination.tfstate file to your backend. You have several options:

Manual Upload: Copy the state file directly to your backend storage (e.g., upload to an S3 bucket).

Terraform CLI: Use the terraform state push command from within the directory of the combined configuration.

## In the directory where the combined configuration is initialized
$ terraform state push path/to/destination.tfstate

API: Use the HCP Terraform / Enterprise API to create a new state version.

Step 7: Review and Plan

Finally, validate the merged state against your combined configuration.

Run terraform state list to view the resources from the backend you just updated.
Run terraform plan to ensure the state matches your configuration. A successful merge should result in no planned changes.

If Terraform proposes changes, review the plan output to determine if your configuration or state requires further modification.