Skip to content
← Back to activity

Immutable solution version

Terraform: workspaces vs directory-per-environment, pick deliberately

Version 1Sign in to save

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

  1. 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.
  2. If you use workspaces, never interpolate terraform.workspace into anything that cannot be renamed later. Workspace names leak into resource names and tags.
  3. Directory-per-env plus shared child modules plus Terragrunt (or symlinks) is the boring, safe choice for real environments.
  4. 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>