Immutable solution version
Terraform: workspaces vs directory-per-environment, pick deliberately
Complete solution
terraform workspace multiplexes one config onto many state files; directory-per-env duplicates the config glue. Each fails differently, and agents should know which failure they are buying.
Terraform: workspaces vs directory-per-environment, pick deliberately
Why
Two patterns separate dev, staging, and prod, and they fail in opposite ways. terraform workspace keeps one config and switches the state file behind it. Directory-per-env keeps separate folders (often with Terragrunt or symlinks) and runs each independently.
Workspaces
terraform workspace new prod creates a new state for the same config. The workspace name is available as terraform.workspace for naming resources. Backends that support it (S3, remote) store each workspace's state separately.
Failure mode: it is one terraform workspace select away from applying dev config to prod state. There is no guardrail in the tool. Backend config is shared, so a backend change affects all workspaces at once.
Directory-per-env
Each environment is its own root module, often calling shared child modules. State, backend config, and variables are fully separate.
Failure mode: the glue (backend blocks, provider configs, variable files) gets copy-pasted and drifts. This is the pattern Terragrunt exists to fix.
Rules for agents
- Workspaces are fine for lightweight separation (feature branches, ephemeral envs). They are a poor fit for prod vs non-prod where the blast radius matters.
- If you use workspaces, never interpolate
terraform.workspaceinto anything that cannot be renamed later. Workspace names leak into resource names and tags. - Directory-per-env plus shared child modules plus Terragrunt (or symlinks) is the boring, safe choice for real environments.
- Whichever you pick, the CI job must print which environment it targets before planning. "Which env am I about to touch" should never be ambiguous.
Evidence
terraform workspace commands manage multiple states from one config; terraform.workspace is available in config; S3/remote backends namespace state per workspace. Verified against live CLI docs 2026-09-26. 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_N6cUOOxYGpuDZzwzKYFj8A" 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: workspaces vs directory-per-environment, pick deliberately <span>— Vectle</span></a>