Skip to main content

Managing Workspaces

Workspaces in the OpenTofu CLI refer to separate instances of state data inside the same OpenTofu working directory. They are distinctly different from workspaces in a cloud backend, which each have their own OpenTofu configuration and function as separate working directories.

OpenTofu relies on state to associate resources with real-world objects. When you run the same configuration multiple times with separate state data, OpenTofu can manage multiple sets of non-overlapping resources.

Workspaces can be helpful for specific use cases, but they are not required to use the OpenTofu CLI. We recommend using alternative approaches for complex deployments requiring separate credentials and access controls.

Managing CLI Workspaces​

Every initialized working directory starts with one workspace named default.

Use the tofu workspace list, tofu workspace new, and tofu workspace delete commands to manage the available workspaces in the current working directory.

Use the tofu workspace select command to change the currently selected workspace. For a given working directory, you can only select one workspace at a time. Most OpenTofu commands only interact with the currently selected workspace. This includes provisioning and state manipulation.

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.

Use Cases​

You can create multiple working directories to maintain multiple instances of a configuration with completely separate state data. However, OpenTofu installs a separate cache of plugins and modules for each working directory, so maintaining multiple directories can waste bandwidth and disk space. This approach also requires extra tasks like updating configuration from version control for each directory separately and reinitializing each directory when you change the configuration. Workspaces are convenient because they let you create different sets of infrastructure with the same working copy of your configuration and the same plugin and module caches.

A common use for multiple workspaces is to create a parallel, distinct copy of a set of infrastructure to test a set of changes before modifying production infrastructure.

Non-default workspaces are often related to feature branches in version control. The default workspace might correspond to the main or trunk branch, which describes the intended state of production infrastructure. When a developer creates a feature branch for a change, they might also create a corresponding workspace and deploy into it a temporary copy of the main infrastructure. They can then test changes on the copy without affecting the production infrastructure. Once the change is merged and deployed to the default workspace, they destroy the test infrastructure and delete the temporary workspace.

When Not to Use Multiple Workspaces​

Workspaces let you quickly switch between multiple instances of a single configuration within its single backend. They are not designed to solve all problems.

When using OpenTofu to manage larger systems, you should create separate OpenTofu configurations that correspond to architectural boundaries within the system. This lets teams manage different components separately. Workspaces alone are not a suitable tool for system decomposition because each subsystem should have its own separate configuration and backend.

In particular, organizations commonly want to create a strong separation between multiple deployments of the same infrastructure serving different development stages or different internal teams. In this case, the backend for each deployment often has different credentials and access controls. CLI workspaces within a working directory use the same backend, so they are not a suitable isolation mechanism for this scenario.

Alternatives to Workspaces​

Instead of creating CLI workspaces, you can use one or more re-usable modules to represent the common elements and then represent each instance as a separate configuration that instantiates those common elements in the context of a different backend. The root module of each configuration consists only of a backend configuration and a small number of module blocks with arguments describing any small differences between the deployments.

When multiple configurations represent distinct system components rather than multiple deployments, you can pass data from one component to another using paired resources types and data sources.

  • If you have a configuration management system accessible from all configurations, then one can use a resource to export variables, while another configuration can use a datasource to import them.

  • In systems that support user-defined labels or tags, use a tagging convention to make resources automatically discoverable. For example, use the aws_vpc resource type to assign suitable tags and then the aws_vpc data source to query by those tags in other configurations.

  • For server addresses, use a provider-specific resource to create a DNS record with a predictable name. Then you can either use that name directly or use the dns provider to retrieve the published addresses in other configurations.

  • If you store a OpenTofu state for one configuration in a remote backend that other configurations can access, then the other configurations can use terraform_remote_state to directly consume its root module outputs. This setup creates a tighter coupling between configurations, and the root configuration does not need to publish its results in a separate system.

Workspace Internals​

Workspaces are technically equivalent to renaming your state file. OpenTofu then includes a set of protections and support for remote state.

Workspaces are also meant to be a shared resource. They are not private, unless you use purely local state and do not commit your state to version control.

For local state, OpenTofu stores the workspace states in a directory called terraform.tfstate.d. This directory should be treated similarly to local-only terraform.tfstate. Some teams commit these files to version control, but we recommend using a remote backend instead when there are multiple collaborators.

For remote state, the workspaces are stored directly in the configured backend. For example, if you use Consul, the workspaces are stored by appending the workspace name to the state path. To ensure that workspace names are stored correctly and safely in all backends, the name must be valid to use in a URL path segment without escaping.

OpenTofu stores the current workspace name locally in the ignored .terraform directory. This allows multiple team members to work on different workspaces concurrently. Workspace names are also attached to associated remote workspaces in a cloud backend. For more details about workspace names in cloud backends, refer to the CLI Integration (recommended) and remote backend and documentation.