Introduction
Splitting two states involves moving resources from an original state to others using using
terraform state mv [options] SOURCE DESTINATION https://www.terraform.io/docs/commands/state/mv.html.Throughout this guide, use the version of Terraform that matches the desired end state to perform the operations.
Procedure
1. Obtain the source state file. This can be done with
terraform state pull > source.tfstate if the configuration has an appropriate backend configuration. If not, the state file can be downloaded directly from their backends (i.e. S3 bucket or Terraform Enterprise workspace) https://www.terraform.io/docs/commands/state/pull.html.2. Backup creation. Make a copy of the state file for a backup.
3. Create a new, empty directory and place the state that will be split into it. This ensures that there are no initialized backend configurations or other state files that may conflict with the following commands.
4. Identify a target state name. In my example I will use
destination.tfstate as the target state. I will move resources from source.tfstate into destination.tfstate.5. View Resources. To view the existing resources in the source state, use
terraform state list -state=source.tfstate > source-resources.txt.6. Move resources. For each item listed in
source-resources.txt that should be split from the source state to the destination state, perform a terraform state mv.Items inside modules (e.g.
module.bar.aws_instance.baz and module.bar.module.qux when moving module.bar ) should not need to be moved, as they will be moved along with their modules.Example: Using local backend, add options
-state=source.tfstate -state-out=destination.tfstate.terraform state mv -state=source.tfstate -state-out=destination.tfstate aws_instance.foo aws_instance.foo
terraform state mv -state=source.tfstate -state-out=destination.tfstate module.bar module.bar
7. View source state and destination state files. Once all of the resources have been moved, check the states to ensure they have the correct contents with
terraform state list -state=source.tfstate. and terraform state list -state=destination.tfstate.
8. Create additional state files. Repeat steps 4-7 to create additional state files as needed to make each state smaller, managing fewer resources.
9. Increment the source state serial. Open
source.tfstate in a text editor and increment the "serial" value by 1 so that it can replace the original source state properly. This is not necessary if the original state is split such that it ends up empty.
10. Upload new states to its final destination. Either (1) Copy the state back to the backend destination manually, such as upload the state to an S3 destination, or (2) upload the state to the backend destination of the split configuration using
terraform state push, or (3) use the Terraform Cloud / Enterprise API to create a new state version. The Terraform Enterprise or Cloud workspace can be created in the web UI first, or can be created using terraform init and a suitable configuration with a remote backend or cloud integration.
# In the directory where the split configuration has been initialized using `terraform init`
terraform state push path/to/destination.tfstate
11. Review. The states are now in place and should be ready for use with split configurations. Run
terraform plan to see the results and ensure that they are as expected. If the configuration and the states were split properly, this should likely show no changes.If changes are proposed and this is unexpected, then review the changes to determine the next steps. Either the state or the configuration will require additional modification. This can involve moving resources to different states or resource addresses, or editing the split configuration to match the state, or other additional changes.