Workspaces for Environments
A Terraform workspace is a named slot that holds its own state file while sharing the same configuration code. Every backend starts with a workspace called default, and running terraform workspace new staging creates an isolated state stream without duplicating any .tf files. Internally, most backends store each workspace's state under a path or key that includes the workspace name (for example env:/staging/terraform.tfstate in an S3 key prefix), so plan and apply in one workspace never touch resources tracked in another. This makes workspaces attractive for quick, low-friction environment separation: the same module tree can provision a dev sandbox and a staging mirror just by switching context.
Cricket analogy: A Terraform workspace is like a franchise running separate squads — first team and reserves — from the identical training manual, each squad's roster and results tracked independently without duplicating the coaching playbook.
How Workspace Selection Affects a Run
The currently selected workspace is exposed inside configuration through terraform.workspace, a read-only string. Teams commonly interpolate it into resource names, tags, or a lookup map so that each environment gets differentiated infrastructure sizing from otherwise identical code, e.g. count = terraform.workspace == "prod" ? 3 : 1. Because the interpreter evaluates this at plan time based on whichever workspace is active, forgetting to switch workspaces before running apply is a classic source of accidentally modifying the wrong environment.
Cricket analogy: terraform.workspace read inside config is like a scoreboard operator checking which match format is live — Test or T20 — to decide whether to show a five-day session count or an over count, and forgetting to switch it shows the wrong display entirely.
Workspaces vs. Separate Root Configurations
Workspaces are best suited to environments that are structurally identical and only differ by scale or a handful of variables. When environments diverge significantly — different provider accounts, different regions, materially different resource sets — most practitioners switch to separate root modules (distinct directories per environment, each with its own backend configuration and variable file) rather than stretching one workspace-driven configuration to cover every case. Mixing both approaches without a clear convention is a common source of confusion on growing teams.
Cricket analogy: Workspaces suiting only-scale-differing environments is like using the same training drills for the U19 and senior squads, just with lighter loads; but a completely different format like the Hundred needs its own separate coaching setup, not a workspace switch.
$ terraform workspace list
* default
$ terraform workspace new staging
Created and switched to workspace "staging"!
You're now on a new, empty workspace. Workspaces isolate their state,
so if you run "terraform plan" Terraform will not see any existing state
for this configuration.
$ terraform workspace show
staging
$ terraform apply -var-file="staging.tfvars"
...
$ terraform workspace select default
Switched to workspace "default".Think of a workspace as a separate save slot in a video game: the world (your configuration code) stays the same, but each slot tracks its own independent progress (state). Switching slots doesn't rewrite the game rules, only which save file gets read and written.
Workspaces do not isolate variable values automatically. If you don't pass a workspace-specific .tfvars file or branch logic on terraform.workspace, both dev and prod will apply identical settings, defeating the purpose of separation. Always pair workspace-aware code with workspace-aware inputs.
- Every backend starts with a
defaultworkspace; new ones are created withterraform workspace new <name>. - Each workspace keeps a fully separate state file while reusing the same configuration source.
terraform.workspaceexposes the active workspace name for use in expressions, tags, and conditionals.- Workspaces suit environments that are structurally similar; use separate root modules for environments that diverge significantly.
- Forgetting to switch workspaces before
applyis a leading cause of accidental cross-environment changes. - Workspace names alone don't vary inputs — combine them with conditional variables or per-workspace
.tfvarsfiles.
Practice what you learned
1. What does creating a new Terraform workspace primarily isolate?
2. Which built-in expression lets configuration code react to the active workspace?
3. What is the name of the workspace that exists automatically in every backend?
4. When are separate root module directories generally preferred over CLI workspaces?
5. What is a common mistake teams make when relying on workspaces for environment separation?
Was this page helpful?
You May Also Like
File and Directory Structure Conventions
Consistent file layout and naming conventions keep Terraform projects navigable as they grow, separating variables, outputs, providers, and resources predictably.
The Terraform State File
Terraform's state file is the source of truth mapping your configuration to real-world resources. Understanding its structure and risks is essential for safe, collaborative infrastructure management.
Remote State Backends
Remote backends store Terraform's state file outside the local disk, enabling team collaboration, durability, and integration with locking mechanisms.
Variables and Variable Types
Input variables let Terraform configurations be parameterized and reused across environments. This topic covers declaring variables, type constraints, defaults, validation, and how to supply values.
Related Reading
Related Study Notes in DevOps
Browse all study notesNginx Study Notes
DevOps · 30 topics
DevOpsAnsible Study Notes
DevOps · 30 topics
DevOpsAdvanced Kubernetes Study Notes
Kubernetes · 30 topics
DevOpsAdvanced Bash Scripting Study Notes
Bash · 30 topics
DevOpsApache Kafka Study Notes
Kafka · 30 topics
DevOpsDocker & Kubernetes Study Notes
YAML · 40 topics