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.

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.

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.