- State
- Workspaces
Workspaces
Each OpenTofu configuration has an associated backend that defines how OpenTofu executes operations and where OpenTofu stores persistent data, like state.
The persistent data stored in the backend belongs to a workspace. The backend initially has only one workspace containing one OpenTofu state associated with that configuration. Some backends support multiple named workspaces, allowing multiple states to be associated with a single configuration. The configuration still has only one backend, but you can deploy multiple distinct instances of that configuration without configuring a new backend or changing authentication credentials.
Backends Supporting Multiple Workspaces
You can use multiple workspaces with the following backends:
Using Workspaces
Workspaces are not appropriate for system decomposition or deployments requiring separate credentials and access controls. Refer to Use Cases in the OpenTofu CLI documentation for details and recommended alternatives.
OpenTofu starts with a single, default workspace named default
that you cannot delete. If you have not created a new workspace, you are using the default workspace in your OpenTofu working directory.
When you run tofu plan
in a new workspace, OpenTofu does not access existing resources in other workspaces. These resources still physically exist, but you must switch workspaces to manage them.
Refer to the OpenTofu CLI workspaces documentation for full details about how to create and use workspaces.
Current Workspace Interpolation
Within your OpenTofu configuration, you may include the name of the current
workspace using the ${terraform.workspace}
interpolation sequence. This can
be used anywhere interpolations are allowed.
Referencing the current workspace is useful for changing behavior based on the workspace. For example, for non-default workspaces, it may be useful to spin up smaller cluster sizes. For example:
Another popular use case is using the workspace name as part of naming or tagging behavior: