Workspaces

A Terraform workspace is a named, separate state under the same configuration and backend — default, dev, prod. The same code, multiple independent states. With an S3 backend, each workspace's state lives at a derived key (env:/dev/...) inside the same bucket.

Workspaces are genuinely useful and routinely misused. They are a clean fit for lightweight, identical parallel copies of the same infrastructure — and a poor fit for the dev-vs-prod separation people most often reach for them to provide, because they share one backend and one set of credentials.

What a Workspace Is

You create and switch workspaces with three commands: terraform workspace new dev, terraform workspace select dev, and terraform workspace list. Each holds an independent state for the same configuration directory, so an apply in dev touches only dev's resources. The starting workspace is always default, and it cannot be deleted.

# create and switch in one step
terraform workspace new dev

# list; the active one is marked with *
terraform workspace list

# switch the active workspace
terraform workspace select prod

The terraform.workspace Value

Inside the config, terraform.workspace resolves to the active workspace name, which you use to branch small differences — an instance count, a name suffix, a smaller machine type in non-prod. Kept to a few values, this is tidy. The moment it spreads into a dozen conditionals, each environment has quietly become a different code path threaded through one file, and the config gets hard to reason about.

resource "aws_instance" "web" {
  instance_type = terraform.workspace == "prod" ? "m5.large" : "t3.micro"
  tags = {
    Environment = terraform.workspace
  }
}

Good Uses

Workspaces shine for ephemeral or parallel copies of identical infrastructure: a per-developer sandbox, a short-lived stack spun up for one pull request and torn down when it merges, a load-test environment that mirrors the real one. The defining trait is sameness — the same code, the same settings, just a separate state so the copies do not collide. When that is what you need, workspaces are the lightest tool for it.

Where Workspaces Fall Short

All workspaces share one backend and one provider configuration, which means one set of credentials and one account. That is weak isolation for prod versus dev: a leaked credential or a bad bucket policy exposes every workspace at once, and there is no account boundary between your sandbox and production. Worse, the active workspace is implicit — the same terraform apply hits a different environment depending on hidden CLI state — so forgetting to select is a real path to applying dev changes to prod.

Workspaces vs Directories

The recurring decision is workspaces versus separate directories (or separate backends) per environment. Workspaces minimize duplication but give weak isolation; separate directories duplicate a little code but give a real blast-radius boundary, per-environment backend config, and a distinct account for prod. Most teams land on isolating production with its own state and account, and reserving workspaces for the ephemeral identical copies they are actually good at. The organization chapter develops this trade-off in full.