Terraform workspaces provide a mechanism to manage multiple instances of infrastructure from a single configuration without duplicating code. The concept applies differently in the Terraform CLI and in HCP Terraform and Terraform Enterprise, and understanding the distinction is essential for safe multi-environment operations.
The core idea is state isolation. Terraform relies on state to associate resources with real-world objects. When you run the same configuration multiple times with separate state data, Terraform can manage multiple sets of non-overlapping resources. Workspaces are the built-in way to achieve that isolation within one working directory.
What Terraform Workspaces Are
Terraform workspaces let you manage multiple, isolated deployments of the same infrastructure configuration, each with its own state file, without duplicating your code.
In practice, Terraform workspaces allow you to manage multiple instances of your infrastructure resources in the same configuration. This is particularly useful when you want to create multiple versions of the same resources, such as staging, testing, or production environments, without having to duplicate your configuration files.
A Terraform workspace is a way to create multiple instances of the same resources within the same configuration. Each workspace has its own set of state files, which means that you can create multiple instances of the same resources without affecting the state files of other instances.
For example, you could create a workspace for your development environment and another workspace for your production environment. Each workspace would have its own set of state files, allowing you to manage your resources independently of each other.
Terraform workspace allows you to create multiple, separate environments or versions of your infrastructure in the same Terraform configuration. The separate state file for each of the environments, i.e., workspaces, helps you manage multiple instances of your infrastructure without interfering with each other. Each of the Terraform deployments in a workspace is linked with its own state file and updated with the desired configuration.
In a nutshell, workspaces enable you to deploy and manage different environments that have an identical Terraform configuration, each with a separate state file.
Workspaces in the Terraform CLI refer to separate instances of state data inside the same Terraform working directory. They are distinctly different from workspaces in HCP Terraform, which each have their own Terraform configuration and function as separate working directories.
CLI Workspaces Versus HCP Terraform Workspaces
The term workspace is overloaded.
With Terraform CLI, workspaces live inside one working directory.
With HCP Terraform and Terraform Enterprise, a workspace is a group of infrastructure resources managed by Terraform.
This topic provides an overview of the workspaces resource in HCP Terraform and Terraform Enterprise. A workspace is a group of infrastructure resources managed by Terraform. Working with Terraform involves managing collections of infrastructure resources, and most organizations manage many different collections. When run locally, Terraform manages each collection of infrastructure with a persistent working directory, which contains a configuration, state data, and variables. Since Terraform CLI uses content from the directory it runs in, you can organize infrastructure resources into meaningful groups by keeping their configurations in separate directories. HCP Terraform manages infrastructure collections with workspaces instead of directories.
Workspaces in the Terraform CLI refer to separate instances of state data inside the same Terraform working directory. They are distinctly different from workspaces in HCP Terraform, which each have their own Terraform configuration and function as separate working directories.
| Aspect | Terraform CLI Workspace | HCP Terraform / Terraform Enterprise Workspace |
|---|---|---|
| Scope | State isolation inside one working directory | A collection of infrastructure with its own configuration |
| State storage | Local terraform.tfstate.d per workspace | Managed by HCP Terraform per workspace |
| Configuration sharing | Same configuration files for all workspaces | Each workspace can have its own configuration |
| Typical use | Dev / Staging / Prod variants of same code | Separate projects or teams |
| Working directory model | One directory, multiple states | One workspace ≈ one working directory |
Terraform CLI workspaces are not required to use the Terraform CLI. We recommend using alternative approaches for complex deployments requiring separate credentials and access controls.
How State Is Stored
Terraform stores information about all managed resources in a state file. It is important to store this file in a secure location. Every Terraform run is associated with a state file for validation and reference.
Every initialized working directory starts with one workspace named default.
When you first use Terraform, you’re already using a workspace. You just don’t know it yet. Every Terraform project starts with a workspace called “default”. It’s similar to the main branch in Git if you’re familiar with version control.
How Terraform Workspaces Store State
When you use the default workspace, Terraform creates a file structure like this:
The default state is typically stored as terraform.tfstate in the working directory.
But when you create a new workspace, something interesting happens. Let’s create one:
terraform workspace new development
Now your folder structure changes:
See that new terraform.tfstate.d folder? That’s where Terraform keeps the state files for all your workspaces except default.
Each workspace maintains a state file, in which it stores the resources managed by Terraform in the specified environment. This isolation means that no change in one working environment, such as your development environment, can affect another, such as production.
The workspaces allow you to maintain a single copy of your Terraform configuration files while managing multiple environments under a single roof.
Creating and Switching Workspaces
Creating a Terraform workspace is easy. First, you’ll need to initialize your workspace by running the following command:
In this example, we create a new workspace called “my-workspace”. Once you have created a new workspace, you can switch to it using the following command:
This command switches your active workspace to “my-workspace”
General commands used with CLI workspaces:
terraform init
terraform workspace list
terraform workspace new development
terraform workspace select my-workspace
You can see which workspace you’re currently using:
terraform init
terraform workspace list
You’ll see output like this:
* default
The star shows which workspace you’re currently using. Right now, it’s just default.
Use the terraform workspace select command to change the currently selected workspace. For a given working directory, you can only select one workspace at a time. Most Terraform commands only interact with the currently selected workspace. This includes provisioning and state manipulation.
Typical Use Cases
Workspaces let you manage multiple deployments of the same configuration. When you create cloud resources using Terraform’s configuration language, they are created in the default workspace. Workspaces are a handy tool for testing configurations, offering flexibility in resource allocation, regional deployments, multi-account deployments, and more.
If you’ve ever needed to spin up a staging environment that mirrors production, test a config change without touching live infrastructure, or deploy the same setup across multiple AWS accounts or regions, workspaces are the feature that makes that clean and manageable.
Use workspaces to manage different environments, such as dev and prod. They are great for testing changes without affecting your main setup. They also help manage different customer deployments.
With the help of Terraform workspaces, multiple environments such as dev or staging can be managed using the same Terraform configuration files. Each of these environments has an isolated and independent state file.
Workspaces manage state files for different environments within one configuration. Terragrunt is a tool that helps you write cleaner, reusable code and manage remote state across many modules.
Modules Versus Workspaces
Modules are for reusing code blocks. They help you build things faster. Workspaces manage different states for that code. They allow you to deploy the same code to other locations.
Workspace in Terraform let you use one codebase for different environments. Each workspace has its own state file. This keeps your development, staging, and production setups separate and clean.
Variable Management and Differentiation
When you provision infrastructure in each workspace, you usually need to manually specify different input variables to differentiate each collection. For example, you might deploy test infrastructure to a different region.
You can create multiple working directories to maintain multiple instances of a configuration with completely separate state data.
The article covers how workspaces work, how they compare to alternatives like Git branches and separate directories, how to manage variables across them, and the best practices you should follow to avoid common pitfalls.
The workspaces allow you to maintain a single copy of your Terraform configuration files while managing multiple environments under a single roof.
Best Practices and Pitfalls
Terraform workspaces are a powerful feature that solves a real problem. They enable you to maintain multiple environments without having to replicate code. They are also embedded into Terraform and thus need no additional installations. They are easy to comprehend but versatile enough to be applied in complicated situations.
Start small. Create dev and prod workspaces for your next project. Use variable files to manage the differences. Tag your resources with the workspace name.
Disclaimer: All use cases of Terraform workspaces discussed here work similarly in OpenTofu, the open-source Terraform alternative. However, to keep it simple and familiar for DevOps engineers, we will use “Terraform workspace” as a catch-all term throughout this blog post.
We recommend using alternative approaches for complex deployments requiring separate credentials and access controls.
A common pattern is:
- Item
- Item
- Item
With proper naming and variable separation, workspaces keep state isolated while sharing code.
Conclusion
Terraform workspaces provide state isolation for multiple deployments from a single configuration in the CLI, and represent distinct configuration collections in HCP Terraform. CLI workspaces share code and variables but keep state separate via terraform.tfstate.d, with default present on every init. HCP Terraform workspaces function as separate working directories with their own configuration.
The model excels for dev, staging, and production variants, regional or multi-account rollouts, and safe testing of changes without affecting live infrastructure. It avoids code duplication and pairs naturally with variable files and resource tagging.
Limitations remain. CLI workspaces share credentials and access controls within a single directory, which is why separate working directories or alternative tooling are advised for highly sensitive or complex multi-tenant scenarios. Understanding the difference between CLI workspaces and HCP Terraform workspaces prevents confusion and misconfiguration.
Effective use starts with clear workspace naming, isolated state, workspace-aware variables, and disciplined switching via terraform workspace select. When applied correctly, workspaces let you maintain multiple environments without replicating code.