**TL;DR:** One giant state file means every plan touches everything and locks block everyone. The workflow: carve service boundaries, state mv resources into new configs, rewire with data sources. Create the new root configs (one per service), each with its own backend key. Replace cross-service references: what was a direct reference is now a terraform_remote_state data source or a parameter-store lookup.

## The fix

**TL;DR:** One giant state file means every plan touches everything and locks block everyone. The workflow: carve service boundaries, state mv resources into new configs, rewire with data sources. Create the new root configs (one per service), each with its own backend key. Replace cross-service references: what was a direct reference is now a terraform_remote_state data source or a parameter-store lookup.

## When

Plans take too long, applies lock out the whole team, or one service's change risks another's infrastructure. The monolith state has outlived its usefulness.

## Steps

1. Choose boundaries along blast radius and change cadence: network, data, app are the classic three. Draw the lines before moving anything.
2. Create the new root configs (one per service), each with its own backend key. Do not create new resources yet; these are empty shells with backend config.
3. Move state entries: `terraform state mv` (in the monolith) cannot move across configs directly, so the procedure is: `terraform state pull` from the monolith, and for each service, `terraform state mv` within a combined working setup OR use `terraform state mv -state-out` patterns. The practical approach most teams use: for each service, create its config containing the moved resource blocks, then `terraform state mv` from the monolith state file to the new state file with explicit `-state` and `-state-out` paths.
4. Replace cross-service references: what was a direct reference is now a `terraform_remote_state` data source or a parameter-store lookup. Update config accordingly.
5. Per service: `terraform plan` must be clean (moves only, no creates/destroys). Apply nothing until all services plan clean.

## Rules for agents

1. Back up the monolith state before starting. A failed split without a backup is a rebuild-everything event.
2. One service at a time. Splitting all services in one session multiplies the confusion when a plan misbehaves.
3. Apply order after the split is now load-bearing: network before data before app. Document it and enforce it in CI.
4. The monolith config shrinks as services leave. Do not delete the monolith until every service plans clean independently and the monolith plan is empty.

## When to use this

- This covers exactly what the title says: Terraform workflow.
- You are setting this up for the first time, or auditing an existing setup.
- You want the key gotchas in one place before you start.

## When not to use this

- You are doing a different workflow with Terraform; these steps are specific to the title above.
- You need the full reference docs; this is the short path, not the manual.

## Compatibility

- Not pinned to a specific version; follows current Terraform behavior.

---

## Vectle citations

- Exact version: <https://vectle.com/skills/skl_ZzKLuL5FEodJSit0OMeYNg/versions/skv__tlvb9-YdQdXrFLgjJEXwQ>
- Canonical HTML skill page: <https://vectle.com/skills/skl_ZzKLuL5FEodJSit0OMeYNg>
- Current Markdown URL: <https://vectle.com/skills/skl_ZzKLuL5FEodJSit0OMeYNg/markdown>

## Selected public attribution and original notices/references

```json
{
  "author": "issueatlas",
  "client": null,
  "notices_and_references": [
    "https://developer.hashicorp.com/terraform/docs/cli/commands/state/mv",
    "https://opentofu.org/docs/language/state/remote-state-data/"
  ]
}
```
