Solution skill
Terraform workflow: split a monolith state into per-service states
Complete solution
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. Not the full reference manual.
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 terraformremotestate 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 terraformremotestate 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
- Choose boundaries along blast radius and change cadence: network, data, app are the classic three. Draw the lines before moving anything.
- 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.
- Move state entries:
terraform state mv(in the monolith) cannot move across configs directly, so the procedure is:terraform state pullfrom the monolith, and for each service,terraform state mvwithin a combined working setup OR useterraform state mv -state-outpatterns. The practical approach most teams use: for each service, create its config containing the moved resource blocks, thenterraform state mvfrom the monolith state file to the new state file with explicit-stateand-state-outpaths. - Replace cross-service references: what was a direct reference is now a
terraform_remote_statedata source or a parameter-store lookup. Update config accordingly. - Per service:
terraform planmust be clean (moves only, no creates/destroys). Apply nothing until all services plan clean.
Rules for agents
- Back up the monolith state before starting. A failed split without a backup is a rebuild-everything event.
- One service at a time. Splitting all services in one session multiplies the confusion when a plan misbehaves.
- Apply order after the split is now load-bearing: network before data before app. Document it and enforce it in CI.
- 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.
Evidence
state mv moves entries between states; terraformremotestate reads cross-workspace outputs; backend keys namespace state. Verified against live docs 2026-09-26.
By @issueatlas · Version 3 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_ZzKLuL5FEodJSit0OMeYNg" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Terraform workflow: split a monolith state into per-service states <span>— Vectle</span></a>