Environments — Workspaces vs Directories

The oldest argument in Terraform layout is whether environments should be CLI workspaces — one backend, switchable state, one set of files — or separate directories with separate config and separate state. The argument outlasts most projects because both genuinely work for small cases and both have failure modes that only show up later.

On GCP the question is reframed by the hierarchy. Because the right isolation boundary is a separate project per environment, separate directories — each targeting its own project with its own state — is almost always the answer. Workspaces fit a few narrow cases, and on every other case they bite production. This topic is about which case you are in.

What a Workspace Actually Is

terraform workspace keeps multiple state instances behind one backend and one configuration, switching which state the same code applies to. It is one directory pretending to be many environments, distinguished only by the value of terraform.workspace at runtime. The .tf files are identical across "environments"; the only thing that differs is which state object the backend selects.

That is the whole mechanism, and it explains both its appeal and its danger. The appeal is near-zero ceremony — terraform workspace new staging and you have a second state. The danger is that prod and staging are the same files and the same backend, separated by one selectable variable that a single command can change.

Why Directories Win on GCP

envs/hatch-app-prod/ and envs/hatch-app-staging/ are separate directories with separate backends, each pinned to its own project. The prod project, the prod state object, and the prod IAM policy are physically distinct from staging's. There is no command you can fat-finger that applies staging code to prod, because applying prod means being in the prod directory, which has the prod backend, which writes the prod state, which authenticates to the prod project.

That physical separation is the GCP-shaped advantage. The previous two topics established that an environment maps to a project and a project carries billing, quota, and IAM. Directories make the Terraform boundary line up with the GCP boundary — one directory, one project, one state — so the thing you most want isolated is isolated at every layer at once.

The Prod-Isolation Failure of Workspaces

With workspaces, prod and staging share one backend and one set of .tf files. A terraform workspace select mistake applies the wrong environment, with no second confirmation — one wrong command and production changed. There is no directory you had to be in, no separate backend that would have refused, just a runtime variable that pointed the same code at the wrong state.

The second failure is divergence. Because the config is identical across workspaces, you cannot safely give prod a resource staging lacks — a prod-only firewall rule, a DR replica — without scattering count = terraform.workspace == "prod" ? 1 : 0 conditionals through the code. Every genuine prod/staging difference becomes a conditional, and the configuration slowly drowns in branching that a directory split would have made plain.

Where Workspaces Genuinely Fit

Workspaces fit short-lived, identical, throwaway environments where the whole point is that they are interchangeable. Per-PR ephemeral previews and per-developer sandboxes are the canonical cases: spin one up, test against it, destroy it, and nobody cares which one it was. There the low ceremony of workspace new is exactly the feature, and the absence of per-environment divergence is fine because there is no divergence to express.

The line is durability. If an environment is meant to last, carry distinct config, and absolutely never be confused with another, it wants a directory. If it is meant to be created, used, and thrown away within a pull request, a workspace's lack of isolation is irrelevant because the environment itself is disposable.

The GCP-Specific Tilt

Here is the asymmetry that settles it. Since environments map to projects and projects carry billing, quota, and IAM, the thing you most want isolated — production — is exactly the thing workspaces isolate least. A workspace shares prod's state backend and config with staging; the GCP hierarchy wants prod's project, billing, and IAM completely separate. The two pull in opposite directions precisely where the stakes are highest.

So on GCP the directories-per-project choice is not a stylistic preference but a near-default. HashiCorp's own guidance steers durable multi-environment layouts to directories, and the project hierarchy makes that guidance sharper: map each environment to its own project, give each a directory and a backend, and reserve workspaces for the disposable cases where interchangeability is the goal.