Skip to main content
Terraform workspaces This lesson introduces Terraform workspaces and shows how a single set of Terraform configuration files can manage multiple isolated state instances. You will learn the workspace commands to create, list, select, and delete workspaces, compare CLI workspaces with separate state files/backends, and identify when workspaces are not appropriate so you can choose alternative approaches.
The image outlines an introduction to Terraform workspaces, detailing four key learning objectives: explaining workspaces, using workspace commands, comparing workspaces with separate state files, and identifying scenarios where workspaces are inappropriate.
Terraform CLI workspaces provide a lightweight way to maintain multiple state snapshots from the same configuration files. Each workspace stores its own Terraform state, enabling you to reuse a single codebase to manage multiple environments (for example: dev, staging, prod) without copying or duplicating the configuration. What workspaces do and do not do:
  • They isolate Terraform state only. They do not automatically create separate cloud accounts, provider configurations, or change resource identifiers.
  • Resource naming collisions can occur when different workspaces deploy resources with identical names to the same provider account. Avoid collisions by making resource names workspace-aware (for example: \local.prefix−{local.prefix}-“).
  • The default workspace is named default. Creating a new workspace does not modify your configuration files.
Terraform CLI workspaces are a state-scoping mechanism only. If you need stronger isolation (different accounts, different backends, or different provider configurations), consider separate state files/backends or separate configurations.
Common workspace commands
Quick comparison: when to use workspaces vs separate backends When not to use workspaces
  • Do not rely on CLI workspaces for isolation across cloud accounts, subscriptions, or provider credentials — they do not change provider endpoints or authentication.
  • Avoid workspaces if environments require significant configuration differences, distinct lifecycles, or unique module compositions.
  • If you need independent CI/CD pipelines, strict access control per environment, or separate backends, prefer separate state backends or Terraform Cloud/Enterprise workspaces (these are different from CLI workspaces).
Practical tips and best practices
  • Make resource names workspace-aware to prevent collisions: \local.prefix−{local.prefix}-“.
  • Always confirm the active workspace before applying changes: terraform workspace show.
  • Keep variable values and small differences parameterized via variables, locals, or input files when using workspaces.
  • Use separate backends or completely separate configurations when you need account-level isolation, different provider blocks, or strict compliance controls.
  • Consider naming conventions and CI workflows that explicitly select or set the workspace before planning/applying to avoid accidental operations in the wrong state.
Additional links and references

Watch Video