How do Terraform workspaces relate to state, and when should you avoid them?
Quick Answer
A workspace lets one configuration manage multiple, isolated state files (e.g., `terraform workspace new staging`) sharing the same backend and code, keyed by workspace name (`terraform.workspace`). They're handy for quick, throwaway environment duplicates but scale poorly for real dev/staging/prod separation, since all workspaces share identical code and provider credentials with no natural place to vary things like account IDs, region, or approval gates per environment. Most teams instead use separate root modules/directories (or separate backends) per environment, reserving workspaces for short-lived, ephemeral copies like PR preview environments.
Detailed Answer
Workspaces are one of the more commonly misused Terraform features — understanding what they actually isolate (and what they don't) is key.
What a workspace does
terraform workspace new staging
terraform workspace select staging
Each workspace gets its own state file, while using the exact same configuration files and backend. Inside configuration, terraform.workspace exposes the current workspace's name, letting you parameterize resource names or behavior:
resource "aws_instance" "web" {
tags = {
Name = "web-${terraform.workspace}"
}
}
With the default local backend, workspace state files are stored under terraform.tfstate.d/<workspace-name>/; with a remote backend like S3, they're typically stored under a workspace-prefixed key.
What it's good for
- Quick, throwaway duplicates of the same infrastructure — e.g., ephemeral PR preview environments, or a personal sandbox copy for testing a change before it hits shared infrastructure.
- Situations where every "environment" really is identical in every way except a name/count.
Where it breaks down for real dev/staging/prod separation
- All workspaces share the same code and the same provider credentials/configuration — there's no natural place to point staging at one AWS account and prod at another, since
providerblocks aren't workspace-aware. - There's no structural barrier stopping someone from running
terraform workspace select prod && terraform applyby mistake from a branch meant for dev changes — the safety net is a manualworkspace select, not a separate directory/pipeline. - Approval gates, variable files, and module version pins usually need to differ meaningfully between environments (prod pinned to an older module version, staging tracking latest) — workspaces don't give you a clean way to vary those per environment either.
The common recommendation
Most teams instead structure environments as separate root modules/directories (environments/dev, environments/prod), each with its own backend config, state, and provider credentials, all calling shared versioned modules. Workspaces are reserved for genuinely ephemeral, structurally-identical copies (like PR previews) — not for the dev/staging/prod boundary itself.