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

TL;DR

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. Failure mode: it is one terraform workspace select away from applying dev config to prod state. Backend config is shared, so a backend change affects all workspaces at once. This is the pattern Terragrunt exists to fix.

When to use

You are seeing this: terraform workspace new prod creates a new state for the same config. Use this skill when you run into "Terraform: workspaces vs directory-per-environment, pick deliberately".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

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.

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.

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.