# Terraform workflow: split one backend key into many without downtime

## When

A single `terraform.tfstate` key holds unrelated resource groups and every plan refreshes all of them. Split by service or lifecycle: things that change together stay together.

## Steps

1. Decide the key layout: one key per service group, e.g. `network/terraform.tfstate`, `data/terraform.tfstate`, `app/terraform.tfstate`. Fewer, stable keys beat many clever ones.
2. Create the new root configs, one per key, each with its own backend block pointing at its key. Move the corresponding resource blocks into each config.
3. Back up the original state: `terraform state pull > backup-monolith-[date].json`.
4. For each new config: `terraform init`, then move entries from the old state file to the new one with explicit state paths:
   `terraform state mv -state=[old-state-file] -state-out=[new-state-file] [address] [address]`
   (Pull the old state to a local file first so the moves are explicit and reviewable.)
5. Push each new state file to its backend key, then per config: `terraform plan` must be clean (moves only).
6. Replace cross-key references with `terraform_remote_state` data sources or parameter lookups.

## Rules for agents

1. Moves are by address, and addresses must match the new config exactly. `terraform state list` on the old state is your source of truth for what exists.
2. One key per change. Splitting three keys in one session triples the chance of moving an address to the wrong key.
3. After the split, the old key should be empty. Verify with a plan against the old config (should propose nothing or be retired), then decommission the old config directory.
4. Apply order between keys is now manual: document network -> data -> app and enforce it in CI. The monolith ordered things for free; the split does not.