Workspaces

A workspace is a named, separate state under the same configuration and backend. terraform.workspace evaluates to the current one, and switching workspaces switches which state file you read and write — the config and the bucket stay the same, only the state object changes. They are a real isolation mechanism, and a frequently misused one.

On GCP, workspaces are usually the wrong tool for environments. The project is already the natural boundary for isolation, and a workspace gives you neither IAM nor quota separation — just a separate state under one shared project and one shared provider config. Knowing exactly what a workspace does and does not isolate is what keeps you from reaching for them where a project belongs.

What a Workspace Is

Run terraform workspace new staging and Terraform creates a second state under the same backend. With the gcs backend, each workspace gets its own state object under the prefix — Terraform writes non-default workspaces to a <prefix>/<workspace>.tfstate path — so default and staging never touch each other's resources even though they share one config and one bucket prefix.

terraform workspace new sandbox-anna   # create and switch to it
terraform workspace list             # * marks the active one
terraform workspace show             # print the active workspace name
terraform workspace select default   # switch back

The active workspace decides which state file the next plan and apply read and write. There is always a default workspace; the others you create explicitly. The prompt does not show which one is active, which is the root of the most common workspace accident.

Referencing the Current Workspace

terraform.workspace is a string you can interpolate into resource names and labels — "hatch-events-raw-${terraform.workspace}" — so one config produces per-workspace resources. This is what makes a workspace useful: the same HCL stamps out an isolated copy of the infrastructure for each workspace, named so the copies do not collide.

It is also the source of the "I applied to the wrong workspace" outage. Because the resource names depend on the active workspace, and the active workspace is not shown in the prompt, it is easy to run an apply meant for one workspace against another — and watch it create or change the wrong copy. Always confirm with terraform workspace show before an apply.

Where Workspaces Actually Fit

Workspaces fit short-lived parallel copies of the same infrastructure. A per-developer sandbox where each engineer wants their own isolated stack of the Hatch pipeline, an ephemeral PR preview spun up and torn down per pull request, a quick experiment you will delete in an hour — these are cases where you want identical resources with isolated state and zero new project plumbing.

The common thread is sameness and impermanence. Every workspace runs the exact same config, and you do not care that they share a project's IAM and quota because they are throwaway. The moment a copy needs to outlive the day or differ from the others, the fit breaks.

Why a Project per Environment Usually Wins on GCP

For dev, staging, and prod, a project per environment is the better boundary. A hatch-pipeline-dev and a separate hatch-pipeline-prod give you separate billing, separate quota, separate IAM policy, and separate blast radius. Workspaces share one project and one provider config, so a fat-fingered apply can hit prod resources with dev's permissions — there is no boundary in between to stop it.

This is the GCP-native isolation. On Google Cloud the project is the real security and cost boundary, and structuring environments as projects (covered in depth in the project-structure chapter) gives you isolation that a workspace, sharing everything but the state object, simply cannot provide.

The Sameness Constraint

Workspaces force every environment through the identical config and provider settings. That is fine while the environments truly are identical, and it falls apart the moment prod needs a different project, a different region, or a different CMEK key. To serve divergent environments from one root, you start sprinkling terraform.workspace == "prod" ? ... : ... conditionals through the config.

Those conditionals sprawl. One or two are tolerable; a dozen scattered across resources turn the config into a branching mess where reading any single resource means tracing which workspace it is for. At that point a separate root module per environment reads cleaner and is harder to misfire — the divergence is the signal to split, not to branch.