Terraform Workspaces and Environment Isolation on GCP — the name, the wall, and the promotion boundary

One configuration wants to run many times: dev, staging, prod. Where those lives are kept apart is where outages are kept apart.

Isolation by name is not isolation by boundary. A workspace gives an environment a name. A boundary gives it a wall.

§ IFrame

The TF arc so far has climbed three rungs. State was Terraform's memory of the world. The module was the reuse boundary that let one piece of code serve many callers. The provider was the reach, the versioned bridge to a real cloud. Today is the fourth rung: what happens when one configuration must run many times. Every team hits this within weeks of the first apply. The same network module, the same bucket module, the same service, needed once for dev, once for staging, once for prod, each with its own state, its own credentials, and its own tolerance for being broken.

Terraform offers two answers, and they are not equal. The first is the workspace: a named copy of state living behind the same backend. The second is the file layout: a directory per environment, each with its own backend and its own identity. Brikman's state chapter spends seven pages on the first answer in order to explain why production belongs to the second, and that argument is the spine of this lesson.

§ IIFoundations — What a Workspace Is

A workspace is a named instance of state for a single configuration against a single backend. Every Terraform working directory has at least one, called default, and the CLI manages the rest: terraform workspace new dev, select dev, show, list. Select a workspace and every plan and apply reads and writes that workspace's state file. The code does not change. The backend does not change. Only the state path changes.

On the GCS backend, the mapping is concrete: with a backend of bucket hedronite-tf-state and prefix envs, the default workspace lives at gs://hedronite-tf-state/envs/default.tfstate and a workspace named dev lives at gs://hedronite-tf-state/envs/dev.tfstate. One bucket, one prefix, many state objects, each named for its workspace. Inside the configuration, terraform.workspace interpolates the current name, and the standard trick keys size off it:

resource "google_compute_instance" "app" {
  count        = terraform.workspace == "prod" ? 3 : 1
  machine_type = terraform.workspace == "prod" ? "e2-standard-4" : "e2-small"
  name         = "app-${terraform.workspace}-${count.index}"
  zone         = "us-central1-a"
}

Ten minutes of learning and the multi-environment problem looks solved. It is solved, for a specific class of environment. The next section names why that class excludes production.

§ IIIMechanism — The Two Flaws of Isolation by Name

The state files share one backend. Every workspace's state object sits in the same GCS bucket, reached with the same credentials, protected by the same IAM policy. If dev state and prod state are objects in one bucket, then every human and every CI job that can touch dev can, by construction, touch prod. There is no way to grant roles/storage.objectAdmin on envs/dev.tfstate while denying it on envs/prod.tfstate in any way a team will actually maintain. The wall you want between a sandbox and the revenue path is missing because the design put both behind one door.

The current workspace is invisible in the code. Which workspace you are in is session state, not repository state. It survives in .terraform/environment on one machine and in one shell's history, and nowhere the reviewer of a pull request can see. The operator who ran terraform workspace select prod on Tuesday to inspect a diff and came back Wednesday to a dev change is one apply from deploying a sandbox experiment into production. The failure requires no malice and no incompetence. It requires only that a human forget one out-of-band fact, which is the most reliable event in operations.

The boundary answer is the file layout: live/dev/, live/staging/, live/prod/, each directory carrying its own backend block pointing at its own bucket. On GCP the walls go up one more level: each environment gets its own project, and each backend bucket lives in that project. The prod state bucket sits in the prod project behind prod IAM. Dev credentials cannot reach it because the boundary is a project boundary, enforced by GCP, visible in every plan.

§ IVWorked Example — The Prod Directory on GCP

The specimen is the prod directory of the layout, wired with the two GCP mechanisms that make the boundary real: a per-environment state bucket and service-account impersonation.

terraform {
  required_version = ">= 1.6"
  backend "gcs" {
    bucket = "hedronite-tf-state-prod"
    prefix = "network"
  }
}

provider "google" {
  project                     = "hedronite-prod"
  region                      = "us-central1"
  impersonate_service_account = "[email protected]"
}

module "network" {
  source  = "git::https://github.com/hedronite/tf-modules.git//network?ref=v1.4.0"
  env     = "prod"
  cidr    = "10.20.0.0/16"
  subnets = 3
}

Read the walls off the code. The backend bucket is hedronite-tf-state-prod, an object store that exists inside the prod project; the dev directory names hedronite-tf-state-dev instead, and neither's credentials resolve the other. The provider impersonates terraform-prod@, a service account that holds deploy rights in the prod project only, so a human runs plans with a personal identity that can impersonate the dev robot freely and the prod robot only through an approval-gated grant. And the module source pins v1.4.0, which is the 07-25 lesson doing its work: dev runs v1.5.0-rc1, staging runs it after dev survives a week, prod runs what staging proved.

That last line is the second coin of the day: the promotion boundary. Change does not move between environments by re-pointing a workspace or editing prod's directory in place. Change moves by promoting a version pin from one directory to the next, through a pull request a reviewer can read. The environments stay put; the code walks across them. The cost of the layout is duplication, three backend.tf files that differ by one word, and the cure is the module composition the 07-25 lesson taught: the directories stay thin because everything real lives in versioned modules.

§ VWhere Workspaces Fit — The Disposable Environment

The critique retires workspaces from production. It does not retire them. The class of environment a workspace serves is the quick experiment, the spike, the copy of infrastructure that exists so one engineer can test one branch and that dies within the day. Call the class the disposable environment, in contrast with the durable one. A disposable environment wants exactly what the workspace offers: instant creation, zero new plumbing, a name, and painless deletion. It does not need its own project, its own bucket, or its own robot, because nothing in it outlives the afternoon and nothing downstream depends on it.

The rule writes itself in two lines. Durable environments (dev, staging, prod, anything a teammate depends on): file layout, own project, own state bucket, own service account, promotion by version pin. Disposable environments (branch spikes, review copies, test fixtures): workspaces or unique-suffix naming, shared sandbox project, deleted by the same automation that made them.

§ VIConnection to Today's Dev and Cert Lessons

Today's Dev lesson is the disposable environment industrialized. A terratest run applies a real module into a real project, asserts against real outputs, and destroys everything in a deferred call that runs whether the assertions passed or failed. Every test run is an environment born and dead inside one go test invocation, kept from colliding with its siblings by unique-suffix naming, which is the workspace idea executed with more discipline than the workspace CLI itself offers. Today's Cert lesson climbs the same idea into the exam blueprint: terraform test spins up ephemeral state, runs its asserts, and auto-destroys in reverse order, while validations and custom conditions guard the durable environments the promotion boundary feeds. One idea at three altitudes: environments you keep, environments you rent, and the gates between them.

§ VIIClosing

A workspace is a named copy of state behind one shared door. A file layout is a wall per environment: its own directory, its own GCS bucket, its own project, its own robot to impersonate. Keep durable environments behind walls and promote change across them by version pin. Spend workspaces on what dies by dinner.

Open the repository that holds your current Terraform. Answer three questions from the code alone: where does prod state live, who can touch it, and what stops a dev credential from reaching it? If any answer requires checking which workspace someone selected, you have found this lesson's work.