Split a monolithic state file
One giant state means any apply can touch anything and a corrupt file loses everything. Split by ownership and blast radius, but move resources without destroying them.
Procedure
- Choose the boundary by lifecycle and ownership, not resource type: networking changes rarely, app resources hourly.
- Move resources with
movedblocks so Terraform rewrites the address instead of destroying: moved { from = aws_db_instance.main to = module.data.aws_db_instance.main } - Or extract into a second state without recreating:
terraform state mv -state-out=networking.tfstate aws_vpc.main aws_vpc.main
Prefer
movedplus a separate apply so the change lives in code, not a manual state edit. - After the split, run
terraform planin both stacks and requireNo changes; a non-empty plan means a resource was recreated or lost. - Update outputs: cross-stack references become
datasources orterraform_remote_state, not a shared root. - Migrate the backend key: create
prod/networkingandprod/appkeys under the same bucket. - Split in a low-traffic window; the split itself is a state write and takes a lock.
- Document which stack owns which resource so the next person imports into the right one.
Pitfalls
- Removing a resource from the new config with no
movedblock orstate rm, destroying it on the next apply. - Using
terraform state mvacross two local files and omitting-state-out, so the resource is in neither. - Splitting mid-incident to shrink the blast radius and adding a second failure mode.
- Cross-stack
terraform_remote_stateon a stack being applied concurrently, causing a stale output. - A split with a non-empty plan that is then applied, silently recreating a database.
Verification
terraform -chdir=app plan # "No changes"
terraform -chdir=networking plan # "No changes"
terraform state list | wc -l # each resource present in exactly one stack
Report: the split boundary, each moved address, and the two empty plans proving nothing was recreated.