CLI Workspaces

Scenario: An engineer, new to the term, assumes a "workspace" must mean a separate directory or Git branch - then, without realizing the CLI's default workspace is still selected, applies genuine production values straight into it.

A CLI workspace is Terraform's built-in way to keep multiple, separate state files for the exact same configuration and backend. Every root module starts with one workspace, literally named default; terraform workspace new dev creates an additional, independent state alongside it, and terraform workspace select <name> switches which one subsequent commands operate against. Inside your configuration, the built-in terraform.workspace value exposes whichever name is currently selected, which is commonly used to vary a resource name per workspace, as shown below.

The genuinely useful case for workspaces is when you want several parallel, ephemeral, structurally identical copies of the same topology - a personal sandbox, a short-lived feature-branch environment. The real danger, and exactly what happened in the scenario above, is that the selected workspace is ambient, invisible context: nothing in your terminal prompt by default reminds you which one is active, so it's alarmingly easy to run a command intending dev while default (or worse, prod) is actually selected. It's also important to know what workspaces don't give you: they do not, by themselves, create separate cloud accounts, separate credentials, or even a separate backend - two workspaces of the same configuration typically still share all of that.

Analogy: CLI workspaces are like tabs in one Excel workbook - each tab holds its own data, but the underlying formulas, macros, and file-level permissions are shared across every tab in that one file. If a formula bug exists, it exists identically on every tab; if the file itself is publicly writable, so is every tab in it.

A worked configuration

terraform workspace new dev
terraform workspace select prod
terraform workspace show

locals { name = "api-${terraform.workspace}" }

Given how easy it is to overlook the active workspace, make it loudly visible everywhere it matters: include it in your shell prompt, print it explicitly at the top of every CI log line, and consider a small validation step that refuses to proceed if the selected workspace doesn't match the environment a pipeline claims to be targeting. Avoid letting terraform.workspace sprawl into a maze of if/for conditionals scattered throughout a configuration that quietly produces entirely different architectures per workspace - at that point you've built several different systems that happen to share one file, which is harder to reason about than just having separate files.

Common mistakes in production

• Running a command assuming a non-default workspace is selected, without checking terraform workspace show first - the default workspace being silently active is one of the most common causes of an unintended production apply.
• Assuming a separate workspace implies separate cloud credentials or a separate backend - by default it does not; both are typically still shared across every workspace of one configuration.

Goal: Treat the plan as a change contract: understand every create, update, replacement, and destroy before approving it. Reinforce this lesson in the tf-workspace-environments Terraform lab. Open /labs/terraform and choose slug tf-workspace-environments; the lab runs real Terraform against the offline FakeCloud provider.