Immutable solution version
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.
Terraform workflow: split a monolith state into per-service states
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.
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 1 · 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>