Skip to main content
Terraform workspaces let a single Terraform configuration manage multiple independent environments by switching which state file is active. The configuration — providers, resources, modules, and variables — is authored once and reused. Terraform acts as the execution engine; the only thing that changes between environments is the active workspace. Each workspace (for example: dev, test, prod) has its own isolated state file while evaluating the same configuration. This enables Terraform to track separate infrastructure lifecycles per environment without duplicating configuration. The core concept is state isolation, not configuration duplication.
The image is a diagram showing Terraform workspaces managing different environments (PROD, TEST, DEV), each with its own state while sharing configuration files. It includes icons for environments, workspaces, and tools like Visual Studio Code, highlighting isolation and state management in infrastructure configuration.
Overview and characteristics Workspaces are a lightweight mechanism to manage multiple state files from one Terraform configuration. They are particularly useful when the same infrastructure topology needs to exist in multiple logical environments. Key characteristics:
Workspaces provide lightweight state isolation for identical infrastructure topologies. Use them when you need separate state files for multiple environments without duplicating configuration.
What workspaces are designed to support Workspaces are intended for scenarios where multiple environments share the same architecture and resource definitions. They are ideal for experimentation, testing, ephemeral feature branches, and short-lived sandboxes that should mirror production topology without requiring separate repositories or duplicated configurations.
The image is a diagram illustrating Terraform workspaces with environments for production, testing, and development, highlighting features such as multiple environment support, lightweight isolation, and simplified testing. It shows the relationship between tfvars, tfstate files, and workspace configuration.
Typical use cases and recommendations
  • Standard environment separation (development, testing, staging, production) when all environments follow the same architecture.
  • Feature branches or ephemeral environments for validating changes without impacting other states.
  • Short-lived sandboxes for experimentation or demos.
If environments diverge significantly (different resources, providers, or modules), prefer separate configurations or dedicated backends rather than forcing divergence through workspaces.
The image illustrates a Terraform workflow with environments for development, testing, and production, using workspaces with tfvars and tfstate files. It also highlights typical use cases like feature testing and temporary environments.
How switching workspaces works Terraform maintains one state file per workspace. When you switch workspaces, Terraform changes which state file is active but does not alter the configuration, providers, or resource definitions. From Terraform’s perspective, the same code is being applied against a different isolated state. Workspaces are effective when environments are structurally identical. They are not a replacement for fully separate configurations or backends if environments have diverged in design or lifecycle requirements. Common Terraform workspace commands Use these commands to manage workspaces locally. Examples:
Example session
Notes about backends and remote state
  • Remote backends typically store workspace-specific state using distinct keys or namespaces, so workspaces are compatible with many remote backends. Backend implementations (for example, Amazon S3 or Consul) may differ in how they manage workspace-related keys.
  • Understand your backend’s semantics before relying on local CLI workspaces for production separation. For example, some hosted platforms treat the workspace concept as a first-class entity and map workspaces to repositories or configurations differently.
  • Further reading:
Key takeaways
  • Workspaces isolate state, not configuration. Use them when multiple environments share the same infrastructure design.
  • They are ideal for light-weight separation: experiments, feature branches, and temporary environments.
  • For long-term divergent environments (different resources or lifecycle requirements), prefer separate configurations or dedicated backends.

Watch Video