How to Split State Files

Introduction

This guide describes how to split a large Terraform state file into multiple smaller ones. You can split a state file by moving resources from a source state to a destination state using the terraform state mv command.

Throughout this guide, use the version of Terraform that matches the desired end state to perform the operations.

Expected Outcome

After completing this procedure, you will have successfully moved resources from a single source state file into one or more new destination state files.

Prerequisites

• Terraform CLI installed.
• Access to the source Terraform state file.

Procedure

1. Create a Backup. Before making any changes, create a backup of the original source state file to prevent data loss.
2. Prepare a New Directory. Create a new, empty directory on your local machine and place the state file you intend to split into it. This isolation prevents conflicts with existing backend configurations or other state files.

3. Pull the Source State File. If the configuration uses a remote backend, pull the state file to your local directory. You can use the terraform state pull command or download it directly from your backend (e.g., an S3 bucket or an HCP Terraform workspace).

   $ terraform state pull > source.tfstate

4. List Resources in the Source State. To view the resources in the source state, use the terraform state list command and redirect the output to a file for easy reference.

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

5. Move Resources to a New State File. For each resource that you want to move into a new state file (destination.tfstate), run the terraform state mv command. Use the -state and -state-out flags to specify the source and destination files when using the local backend.

   When you move a module, Terraform automatically moves all resources contained within it.

   Move a single resource.

   $ terraform state mv -state=source.tfstate -state-out=destination.tfstate aws_instance.foo aws_instance.foo

   Move an entire module.

   $ terraform state mv -state=source.tfstate -state-out=destination.tfstate module.bar module.bar

6. Verify the State Files. After moving the resources, check the contents of both state files to confirm the changes.

   Check the source state.

   $ terraform state list -state=source.tfstate

   Check the new destination state.

   $ terraform state list -state=destination.tfstate

7. Create Additional State Files (Optional). To create more state files, repeat steps 5-6 for each new state you wish to create.
8. Increment the Source State Serial. Open the modified source.tfstate file in a text editor and increment the "serial" value by 1. This step is necessary for the backend to accept the updated state file. You can skip this step if you moved all resources out of the source state, leaving it empty.

9. Upload the New State Files. Upload the newly created state files to their final backend destinations. You have several options:

   • Manual Upload: Manually copy the state file to its backend destination (e.g., upload to an S3 bucket).
   • Terraform CLI: Use terraform state push from within an initialized directory configured with the target backend.
   • API: Use the HCP Terraform or Terraform Enterprise API to create a new state version.

   The following example demonstrates pushing a state file from a local path.

   ## In the directory where the split configuration has been initialized
   $ terraform state push path/to/destination.tfstate

10. Review and Validate. Run terraform plan with the new, smaller configuration that corresponds to one of the split state files. If the state and configuration were split correctly, the plan should report no changes.

    If the plan proposes unexpected changes, review the output to determine whether you need to modify the state or the configuration further.