DevOps
Terraform Workspace Cleanup: Retire Environments After State Moves
Terraform workspaces can become stale after environments move to new accounts, state is split into smaller stacks, or preview infrastructure is replaced. The old workspace may still contain state, variables, backend locks, and automation references. Removing it casually can erase the only map of resources that were never imported into the new structure.
This cleanup is for infrastructure teams trying to retire old workspace names without confusing state removal with resource deletion.
Treat workspace state as evidence
Start by identifying what the workspace still knows: resources, outputs, variables, backend location, last apply, automation that selects it, and owners.
| Workspace clue | What to inspect | Cleanup concern |
|---|---|---|
| No recent apply | CI history and deployment cadence | Some environments change rarely |
| Empty or tiny state | Migration records and imports | State may have moved correctly, or been lost |
| Outputs referenced | Downstream stacks and scripts | Removing outputs can break automation |
| Variables still set | Secrets, account ids, and environment names | Stale values may recreate old resources |
| Backend locks | Failed runs or abandoned automation | Cleanup may mask a broken process |
Use plan and state inspection in a read-only mindset. The first review should produce a worksheet, not changes.
Do not rush these workspaces
Slow down when the workspace represents production, disaster recovery, shared networking, DNS, certificates, or security controls. Also slow down when state was migrated manually; the old workspace may be the only evidence needed to reconcile drift.
Retire in the right order
First, confirm whether every resource is either intentionally destroyed, imported elsewhere, or no longer real. Second, update automation so no pipeline selects the workspace. Third, archive state metadata and migration notes for audit and rollback. Fourth, remove variables and secrets from the workspace. Only then should the workspace itself be retired.
If the workspace stays, rename or document the reason. A stale-looking workspace called legacy-prod should not require tribal knowledge to explain.
Prevent workspace sprawl
New workspaces should be created through a template that records owner, environment type, backend, related account or cluster, and retirement condition. Preview or migration workspaces should have expiry dates. State migration pull requests should include a cleanup checklist for old workspace variables, automation, and documentation.
Key takeaways
- Terraform workspace cleanup must distinguish state from resources.
- Outputs, variables, and automation references can keep a workspace relevant.
- Archive migration evidence before removing stale state.
- New workspaces should start with ownership and retirement metadata.