Workspace Basics with the CLI

You have one directory of Terraform and three tiers to serve — dev, staging, production. You do not want three copies of the configuration (not yet); you want three separate states. That is the whole trick, and the official docs put it bluntly: workspaces are technically equivalent to renaming your state file. Everything else is bookkeeping around that rename.

Five commands cover the entire feature:

terraform workspace list            # *default   dev   staging   production
terraform workspace new staging     # Created and switched to workspace "staging"!
terraform workspace select staging  # Switched to workspace "staging".
terraform workspace show            # staging
terraform workspace delete staging  # refused while the workspace tracks resources

Read the outputs closely. list marks the active workspace with * and always shows default. new both creates and switches to the workspace — there is no second confirm step. select fails on an unknown name unless you pass -or-create. delete refuses while the workspace still tracks resources unless you add -force, and default itself can never be deleted: it is the workspace you have been using all along without knowing it.

Where does the second state file live? With the local backend, Terraform creates a directory for you:

terraform.tfstate            # the default workspace — the file you already had
terraform.tfstate.d/
├── dev/terraform.tfstate
├── staging/terraform.tfstate
└── production/terraform.tfstate

With a remote backend the layout belongs to the backend, and knowing it lets you read the bucket console with confidence. The S3 backend stores the default workspace's state at exactly the key you configured, and every other workspace under a prefix — env: by default:

s3://acme-tfstate/main/terraform.tfstate                 # default workspace
s3://acme-tfstate/env:/staging/main/terraform.tfstate    # workspace "staging"

workspace_key_prefix replaces env: when that prefix clashes with another team's convention. Notice the asymmetry: the default workspace is special-cased in the storage layout — no prefix at all — which is one more reason to give real environments named workspaces and leave default for throwaway experiments.

Your current selection is local bookkeeping, not remote state. Terraform writes the name into .terraform/environment inside the ignored .terraform directory, and every command in that directory reads it back. Two consequences bite routinely. A fresh clone plus terraform init drops you onto default, a silent reset that ends with an apply against the wrong state. And the selection is per directory, not per shell: switch workspaces in one terminal and every other terminal pointed at that directory switches with it.

Pipelines select a workspace without a prompt using TF_WORKSPACE:

TF_WORKSPACE=staging terraform apply -input=false -auto-approve

HashiCorp's own docs warn that this variable "is recommended only for non-interactive usage, since in a local shell environment it can be easy to forget the variable is set and apply changes to the wrong state." Keep it in the pipeline definition, never in your shell profile.

Switching workspaces is cheap precisely because so little moves. Hold on to this split whenever you reason about blast radius:

The switch changes which world you are editing, never the description of that world — which is also why a wrong-workspace mistake cannot be caught in code review: the pull request diff is byte-identical no matter which workspace the next apply lands in.

None of this runs before terraform init has configured the backend — and on a locked-down network init also has to source provider plugins from a filesystem or network mirror, exactly the ground covered by Provider Mirrors for Air-gapped Networks. Once init succeeds, workspace commands are pure state bookkeeping: the configuration on disk never changes, so nothing about a workspace switch can be reviewed in a pull request. That is a strength — zero config churn — and it is also the reason the next topic has to ask whether this mechanism is the right isolation tool for permanent tiers, which is where Workspace Design Tradeoffs picks up.

A workspace is not only a state filename; it is a value your configuration can read. terraform.workspace evaluates to the current workspace name as a string — "default" when nothing was selected — and you can use it anywhere an expression is allowed. That single value is how one set of .tf files serves three environments.

The pattern that scales is a map of environment settings keyed by workspace name:

locals {
  env_config = {
    default    = { count = 1, type = "t3.micro" }
    dev        = { count = 1, type = "t3.micro" }
    staging    = { count = 2, type = "t3.small" }
    production = { count = 6, type = "m5.large" }
  }

  env = local.env_config[terraform.workspace]
}

resource "aws_instance" "web" {
  count         = local.env.count
  instance_type = local.env.type
  ami           = var.ami_id

  tags = {
    Name        = "web-${count.index}"
    Environment = terraform.workspace
  }
}

Deliberately write the lookup with no fallback default. If someone creates a workspace named prod while the map expects production, local.env_config[terraform.workspace] fails with an Invalid index error at plan time — a loud, cheap failure. Compare that with lookup(local.env_config, terraform.workspace, local.env_config.default), which quietly gives a typo'd workspace the default sizing and lets a misnamed workspace drift for weeks.

For resources that exist in exactly one tier, guard with count:

resource "aws_wafv2_web_acl" "edge" {
  count   = terraform.workspace == "production" ? 1 : 0
  name    = "edge-waf"
  scope   = "REGIONAL"
  default_action { allow {} }
}

Use terraform.workspace for tagging as well — Environment = terraform.workspace puts the workspace name on every resource in the cloud console, which is the cheapest possible defence against "which environment is this?" support tickets.

Conditional sets work the same way when the shape of the environment differs rather than its size:

locals {
  services = terraform.workspace == "production" ? toset(["api", "worker", "scheduler"]) : toset(["api"])
}

resource "aws_ecs_service" "this" {
  for_each = local.services
  name     = "payments-${each.value}"
  cluster  = aws_ecs_cluster.this.arn
}

The same value is useful outside resource bodies: publish it as an output — output "workspace" { value = terraform.workspace } — so a pipeline can assert in the plan summary which workspace it just ran against, and pass it into module inputs so child modules receive the environment instead of re-deriving it. One decision point beats N modules each reading terraform.workspace independently; when a tier is renamed, there is exactly one line to change.

The guard that actually stops a wrong-workspace run belongs in a lifecycle precondition:

resource "terraform_data" "workspace_guard" {
  input = terraform.workspace

  lifecycle {
    precondition {
      condition     = terraform.workspace == var.expected_workspace
      error_message = "This root must run against the expected workspace."
    }
  }
}

Set expected_workspace from -var-file or TF_VAR_expected_workspace in the pipeline. A failing precondition aborts the plan with an error; a check block (Terraform 1.5+) with the same assertion only emits a warning and lets the run continue. Choose deliberately which of those you want when the assertion is wrong.

Three limits are worth memorising because interviews ask about them. First, terraform.workspace cannot appear in the backend block: backend arguments are literals evaluated before the configuration graph exists, so the backend key is fixed and the backend appends the workspace prefix itself. Second, variable definition files are not workspace-aware — terraform.tfvars loads identically in every workspace, so per-environment inputs must arrive through -var-file or TF_VAR_ chosen by the caller, not through a file that lives in the directory. Third, count = terraform.workspace == "x" ? 1 : 0 branches multiply: a handful is readable, a dozen turns the configuration into a matrix of conditionals that only one engineer understands.

The guarantee is narrow and precise: each workspace gets an independent state, and a plan in one workspace cannot see any resource tracked in another. Two roots can both declare aws_s3_bucket.data because they are writing different state objects. On S3 that means separate locks too — main/terraform.tfstate.tflock and env:/staging/main/terraform.tfstate.tflock — so a teammate applying staging never contends with your dev apply, while two people in the same workspace still queue on one lock.

Everything outside the state file is shared, and that is where the damage comes from:

Four failure modes follow from that table.

1. Wrong-workspace apply. The diff for staging and production is structurally identical — same addresses, same module tree — so a glance at the plan tells you nothing about which state you are about to rewrite. The only in-band confirmation is terraform workspace show. Build the habit: print it before every apply, and print it in the CI log.

2. The typo that creates an environment. terraform workspace new stagging succeeds. You now have an empty state, so the next plan proposes to create the entire estate from scratch — and applying it in a shared account half-succeeds before name collisions abort the run, leaving orphaned resources behind. Guard scripts with terraform workspace list | grep -qx "$ENV" before proceeding.

3. Deleting a workspace orphans infrastructure. terraform workspace delete -force discards the state, and Terraform documents the result as dangling resources: they physically exist but are no longer manageable. Destroy first, delete second — and never use -force against a state you have not read.

4. Cross-workspace reads are explicit or absent. A terraform_remote_state data source has an optional workspace argument; omit it and you read that backend's default workspace, not the one you happen to be standing in. Mirroring the current workspace is the pattern that keeps tiers aligned:

data "terraform_remote_state" "network" {
  backend   = "s3"
  workspace = terraform.workspace
  config = {
    bucket = "acme-tfstate"
    key    = "network/terraform.tfstate"
  }
}

Leave workspace out and staging quietly consumes default, which is normally empty — the failure surfaces far away from its cause. Every consumption edge between tiers must name its workspace explicitly, because state isolation means nothing propagates automatically.

One property cuts the other way, in your favour: the lock is per state object. Two workspaces in the same bucket lock different keys, so a colleague's apply in dev never queues behind your staging run. That concurrency is real, which means CI must serialise environments by intention — ordered needs: chains, manual gates — rather than expecting state locking to enforce order for you.

Notice also what isolation does not give you: production state is protected by the same bucket and the same credentials as staging, so a developer who can run terraform state pull in dev can usually read production's state too. That is the isolation workspaces never do, and it is the first argument you will meet for splitting environments into separate directories — the subject of Workspace Design Tradeoffs.