Lesson 11 intermediate

Terraform Workspaces

Run several copies of one configuration with separate state using CLI workspaces, see where their state lives, decide between workspaces, folders per environment, HCP Terraform workspaces and Stacks, and avoid the classic mistakes.

Orbit now needs the same stack several times: dev on your laptop, a short-lived copy for each feature branch, and staging on the shared host. The code is identical; only the inputs and the state differ. Terraform offers several ways to get there, and the word workspace means slightly different things in each. This lesson untangles them.

CLI workspaces: several states, one folder

Every Terraform folder starts with one workspace, called default. A CLI workspace is simply another, independent state for the same configuration and backend:

$ terraform workspace show
default
$ terraform workspace new feature-search
Created and switched to workspace "feature-search"!
$ terraform apply -var-file=dev.tfvars
$ terraform workspace list
  default
* feature-search
$ terraform workspace select default
$ terraform workspace select -or-create feature-upload

Each workspace has its own state, so terraform apply in feature-search cannot touch what default created. Since Terraform 1.16, terraform workspace list -json gives a machine-readable list for scripts that clean up old workspaces.

Using the workspace name in code

Inside the configuration, terraform.workspace holds the current name. Use it to keep names unique:

locals {
  stack = terraform.workspace == "default" ? var.environment : "${var.environment}-${terraform.workspace}"
}

resource "docker_container" "web" {
  name  = "orbit-${local.stack}-web"
  image = docker_image.web.image_id

  ports {
    internal = 80
    external = var.web_port + (terraform.workspace == "default" ? 0 : 100)
  }
}

Without that, two workspaces would both try to create a container called orbit-dev-web on the same Docker host, and the second apply would fail.

Where workspace state lives

Backenddefault workspaceOther workspaces
localterraform.tfstateterraform.tfstate.d/<workspace>/terraform.tfstate
s3<key>env:/<workspace>/<key> (prefix set by workspace_key_prefix)
azurerm<key><key>env:<workspace>
HCP Terraform (cloud block)each CLI workspace maps to an HCP Terraform workspace

All workspaces share the same backend and credentials. That is the most important limitation, and it decides when they fit.

When CLI workspaces fit

CLI workspaces are great for temporary, identical copies that share an account and a blast radius:

  • A preview stack per feature branch, created by CI and destroyed when the branch merges.
  • Several developers each running their own copy in a sandbox account.
  • Load-test copies that live for an afternoon.

They are a poor fit for dev, staging and production:

  • Same backend, same credentials: the person who can apply to dev can apply to prod by forgetting one workspace select.
  • The current workspace is invisible state on your machine, not something you see in the code or in the pull request.
  • Real environments differ more than inputs: production has extra monitoring, different sizes, sometimes extra resources. Workspaces push you toward terraform.workspace == "prod" ? ... : ... everywhere.

The classic accident. You tested a destroy in a feature workspace, switched terminals, and ran terraform destroy again in a shell still on staging. Always print the workspace in your shell prompt, or avoid long-lived workspaces for real environments.

Folders per environment

The most common layout for long-lived environments is a small root module per environment that calls shared modules:

infra/
├── modules/
│   ├── orbit-app/
│   └── cache/
└── envs/
    ├── dev/
    │   ├── main.tf          # module "orbit" { source = "../../modules/orbit-app" ... }
    │   └── backend.tf       # key = "orbit/dev/terraform.tfstate"
    ├── staging/
    └── prod/
        ├── main.tf
        └── backend.tf       # different bucket, different account

Each environment has its own backend (even its own cloud account), its own credentials and its own pipeline permissions. Differences are visible in code review. The cost is a little repetition in each main.tf, which modules keep small.

HCP Terraform workspaces

In HCP Terraform, a workspace is a bigger idea: a state, plus its variables, its credentials, its run history, its permissions and its link to a folder in a Git repository. Connecting with the cloud block and tags lets one folder target several of them:

terraform {
  cloud {
    organization = "orbit"

    workspaces {
      tags = ["orbit-app"]
    }
  }
}
$ terraform workspace list
  orbit-app-dev
* orbit-app-staging
  orbit-app-prod

Here each workspace has its own credentials and approval rules, which removes the main weakness of CLI workspaces. HCP Terraform Stacks go one step further: they deploy many copies of a set of components (for example one per region or per customer) and handle the order between them, for platforms where folders per environment would mean dozens of folders.

Choosing

NeedUse
Throwaway copies (branches, tests) in one accountCLI workspaces
Long-lived dev, staging, prodFolders per environment calling shared modules
Per-environment credentials, approvals and run historyHCP Terraform workspaces (or your CI with separate jobs per folder)
Many near-identical deployments (regions, tenants)HCP Terraform Stacks, or generated folders

Cleaning up

A workspace must be empty before it can be deleted:

$ terraform workspace select feature-search
$ terraform destroy -var-file=dev.tfvars
$ terraform workspace select default
$ terraform workspace delete feature-search
Deleted workspace "feature-search"!

Terraform refuses to delete a workspace whose state still tracks resources unless you add -force, which would orphan those resources. Destroy first.

Quick reference

TaskCommand
Current workspaceterraform workspace show
List workspacesterraform workspace list
List as JSON (1.16)terraform workspace list -json
Create and switchterraform workspace new feature-search
Switch, creating if neededterraform workspace select -or-create feature-search
Delete an empty workspaceterraform workspace delete feature-search
Workspace name in codeterraform.workspace
Pick a workspace without switching (CI)TF_WORKSPACE=feature-search terraform plan

Exercise

Two developers each want a private copy of Orbit for a day, in the same sandbox Docker host and backend. What fits best?

  1. A CLI workspace each, with terraform.workspace in resource names
  2. A copy of the whole repository per developer
  3. A new S3 bucket per developer
  4. One shared state with -target for each developer’s resources
Show answer

Answer: A. CLI workspaces give each copy its own state in the same backend. Including the workspace name in resource names keeps them from colliding on the shared host.

Exercise

Why do many teams avoid CLI workspaces for dev, staging and production?

  1. Workspaces cannot have different variable values
  2. Terraform limits a backend to three workspaces
  3. All workspaces share one backend and set of credentials, and the active workspace is easy to get wrong
  4. Workspaces do not support remote state
Show answer

Answer: C. Workspaces only separate state. Production usually needs separate credentials, accounts and approvals, which folders per environment or HCP Terraform workspaces provide.

Key takeaways

  • A CLI workspace is another state for the same configuration and backend.
  • Use terraform.workspace in names so copies do not collide.
  • CLI workspaces suit temporary copies; long-lived environments usually get their own folder and backend.
  • HCP Terraform workspaces add per-workspace variables, credentials and approvals; Stacks orchestrate many deployments.
  • Destroy before deleting a workspace, and always know which one you are in.

FAQ

Is the default workspace special?

Only in that it always exists and cannot be deleted. Some teams never use it, so a missing workspace select fails loudly instead of touching the wrong stack.

Can workspaces use different providers or regions?

They share the configuration, so only through variables: for example region = var.region with a different tfvars file per workspace. If the differences grow, switch to folders.

How does CI choose a workspace?

Set the TF_WORKSPACE environment variable before running Terraform. It selects (but does not create) the workspace without changing local state on the runner.

Are OpenTofu workspaces the same?

Yes, the CLI workspace commands and terraform.workspace (spelled the same in OpenTofu) behave identically.

↑ ↓ navigate Enter open Esc close