Workspaces and Environments

1The Goal

Dev, staging and production should be built from the same code, differing only in inputs (sizes, counts, domains, feature toggles) — so that what you tested in staging is what runs in production. Each environment needs its own state so changes can be planned and applied independently.

There are three common ways to organize that.

2Option A: CLI Workspaces

terraform workspace new staging
terraform workspace select staging
terraform apply -var-file=staging.tfvars

locals {
  env  = terraform.workspace                     # "default", "staging", "prod"
  size = { staging = "t4g.small", prod = "m7g.large" }[local.env]
}

Each workspace gets a separate state (in S3: env:/staging/<key>). Pros: no code duplication, quick. Cons: the environment is invisible in the code and easy to get wrong ("which workspace am I in?" → applied to prod); all environments share one backend configuration and the same credentials; environments can't diverge structurally. HashiCorp itself recommends CLI workspaces mainly for short-lived variations (e.g. per-branch test environments), not for prod vs dev isolation.

3Option B: Directory per Environment (Recommended for Most Teams)

infra/
  modules/                 # reusable modules (service, network, database)
  live/
    dev/
      network/   main.tf  backend.tf  terraform.tfvars
      services/  main.tf  backend.tf  terraform.tfvars
    staging/ …
    prod/
      network/   main.tf  backend.tf (key = prod/network)  terraform.tfvars
      services/ …

Each live/<env>/<unit> is a tiny root module that calls shared modules with environment-specific values and has its own backend key (and ideally its own AWS account and credentials). Pros: explicit, reviewable, per-environment permissions, environments can roll out module versions at different times (dev on v2.1, prod still on v2.0). Cons: some boilerplate (backend and provider blocks repeated) — tools like Terragrunt remove it with include and generated backends.

4Option C: HCP Terraform / Terraform Enterprise Workspaces

Not the same as CLI workspaces: each workspace is a fully separate configuration binding (VCS repo/directory + variables + state + permissions + run history), with policy checks and approvals. Common in larger organizations; conceptually similar to Option B with a managed control plane.

5Promotion Between Environments

PR merged → plan+apply dev automatically
           → plan staging, apply after tests pass
           → plan prod, apply after manual approval (protected environment)

Promote the same module versions and the same artifact references (image digests). With directory-per-environment, promotion is a PR that bumps the module ref/version or variable in the next environment's folder.

6Keeping Environments Honest

• Differences between environments should be intentional and few: counts, sizes, domains — not different resource types or missing components.
• Separate AWS accounts per environment (blast radius, IAM isolation, cost visibility) — devops-cloud/aws/…multi_account….
• Production apply credentials only in the pipeline, not on laptops.
• Ephemeral preview environments per PR (where cost allows) using workspaces or a unique prefix, destroyed on merge.

Under the HoodHow Workspaces Change the State Path▾

For the S3 backend, the default workspace stores state at key; any other workspace stores it at <workspace_key_prefix>/<workspace>/<key> (prefix defaults to env:). terraform workspace select simply changes which object Terraform reads and locks; nothing else in the configuration changes unless you reference terraform.workspace. The current workspace name is stored locally in .terraform/environment — which is exactly why it's easy to be in the wrong one: a fresh clone defaults to default, and a stale terminal keeps whatever was selected last. Directory-per-environment avoids this hidden state: the environment is the path you cd into, visible in the code review, the CI job and the backend key.

⚠️ Common Pitfalls

1. Applying to the wrong CLI workspace.
2. Copy-pasted environment folders that drift (resources added only in prod).
3. Shared credentials across environments — a dev mistake can touch prod.
4. Promoting by re-editing prod by hand instead of promoting versions.
5. terraform.workspace conditionals everywhere — environment logic scattered across resources.

📋 Quick Reference

same code, different inputs, separate state per environment
CLI workspaces: quick, hidden context — ok for ephemeral envs
directory per env (+ Terragrunt): explicit, per-env backend/account/permissions — default choice
promote module versions + artifact digests dev → staging → prod with approvals

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

✅ Check yourself

Source: tf_workspaces_and_environments_theory.md · generated by tools/build_lessons.py