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
| Backend | default workspace | Other workspaces |
|---|---|---|
| local | terraform.tfstate | terraform.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
devcan apply toprodby forgetting oneworkspace 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
| Need | Use |
|---|---|
| Throwaway copies (branches, tests) in one account | CLI workspaces |
| Long-lived dev, staging, prod | Folders per environment calling shared modules |
| Per-environment credentials, approvals and run history | HCP 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
| Task | Command |
|---|---|
| Current workspace | terraform workspace show |
| List workspaces | terraform workspace list |
| List as JSON (1.16) | terraform workspace list -json |
| Create and switch | terraform workspace new feature-search |
| Switch, creating if needed | terraform workspace select -or-create feature-search |
| Delete an empty workspace | terraform workspace delete feature-search |
| Workspace name in code | terraform.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?
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?
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.workspacein 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.