Module 6: Terraform State Management

Lesson 6.5: CLI Workspaces

Plain language

CLI workspaces let one configuration and one backend hold multiple named states.

Shell
terraform workspace list            # * marks the current one
terraform workspace show
terraform workspace new staging     # create and switch
terraform workspace select default
terraform workspace select -or-create dev
terraform workspace delete staging  # must be empty unless -force
  • Every backend starts with a default workspace, which can't be deleted.
  • Inside configuration, terraform.workspace returns the current name: name = "web-${terraform.workspace}".
  • The TF_WORKSPACE environment variable selects a workspace without running select.

Under the hood

Backend Where workspace state lives
Local terraform.tfstate.d/<name>/terraform.tfstate
S3 Under an env:/<name>/ prefix, configurable with workspace_key_prefix
Others Equivalent separate keys, if the backend supports multiple workspaces

When to use CLI workspaces

HashiCorp's guidance: CLI workspaces suit temporary or parallel copies of the same infrastructure, such as testing a feature branch. They aren't suitable when environments need separate credentials or access controls, because every workspace shares the same backend and configuration. For strongly isolated environments like prod and dev, use separate configurations or backends, or HCP Terraform workspaces.

CLI workspaces vs. HCP Terraform workspaces

CLI workspace HCP Terraform workspace
What it is Another named state in the same backend A full unit of work: state, variables, run history, VCS settings, permissions, policies
Separate variables No. Same config and tfvars. Yes, per workspace
Separate access control No Yes, team permissions per workspace or project
Run history and audit No Yes

Module 8 covers HCP Terraform workspaces in detail.