79 lines
4.0 KiB
Plaintext
79 lines
4.0 KiB
Plaintext
---
|
|
page_title: Managing Workspaces - Terraform CLI
|
|
description: >-
|
|
Commands to list, select, create, and output workspaces. Workspaces help
|
|
manage different groups of resources with one configuration.
|
|
---
|
|
|
|
# Managing Workspaces
|
|
|
|
In Terraform CLI, _workspaces_ are separate instances of
|
|
[state data](/language/state) that can be used from the same working
|
|
directory. You can use workspaces to manage multiple non-overlapping groups of
|
|
resources with the same configuration.
|
|
|
|
- Every [initialized working directory](/cli/init) has at least
|
|
one workspace. (If you haven't created other workspaces, it is a workspace
|
|
named `default`.)
|
|
- For a given working directory, only one workspace can be _selected_ at a time.
|
|
- Most Terraform commands (including [provisioning](/cli/run)
|
|
and [state manipulation](/cli/state) commands) only interact
|
|
with the currently selected workspace.
|
|
- Use [the `terraform workspace select` command](/cli/commands/workspace/select)
|
|
to change the currently selected workspace.
|
|
- Use the [`terraform workspace list`](/cli/commands/workspace/list),
|
|
[`terraform workspace new`](/cli/commands/workspace/new), and
|
|
[`terraform workspace delete`](/cli/commands/workspace/delete) commands
|
|
to manage the available workspaces in the current working directory.
|
|
|
|
-> **Note:** Terraform Cloud and Terraform CLI both have features called
|
|
"workspaces," but they're slightly different. Terraform Cloud's workspaces
|
|
behave more like completely separate working directories.
|
|
|
|
## The Purpose of Workspaces
|
|
|
|
Since most of the resources you can manage with Terraform don't include a unique
|
|
name as part of their configuration, it's common to use the same Terraform
|
|
configuration to provision multiple groups of similar resources.
|
|
|
|
Terraform relies on [state](/language/state) to associate resources with
|
|
real-world objects, so if you run the same configuration multiple times with
|
|
completely separate state data, Terraform can manage many non-overlapping groups
|
|
of resources. In some cases you'll want to change
|
|
[variable values](/language/values/variables) for these different
|
|
resource collections (like when specifying differences between staging and
|
|
production deployments), and in other cases you might just want many instances
|
|
of a particular infrastructure pattern.
|
|
|
|
The simplest way to maintain multiple instances of a configuration with
|
|
completely separate state data is to use multiple
|
|
[working directories](/cli/init) (with different
|
|
[backend](/language/settings/backends/configuration) configurations per directory, if you
|
|
aren't using the default `local` backend).
|
|
|
|
However, this isn't always the most _convenient_ way to handle separate states.
|
|
Terraform installs a separate cache of plugins and modules for each working
|
|
directory, so maintaining multiple directories can waste bandwidth and disk
|
|
space. You must also update your configuration code from version control
|
|
separately for each directory, reinitialize each directory separately when
|
|
changing the configuration, etc.
|
|
|
|
Workspaces allow you to use the same working copy of your configuration and the
|
|
same plugin and module caches, while still keeping separate states for each
|
|
collection of resources you manage.
|
|
|
|
## Interactions with Terraform Cloud Workspaces
|
|
|
|
Terraform Cloud organizes infrastructure using workspaces, but its workspaces
|
|
act more like completely separate working directories; each Terraform Cloud
|
|
workspace has its own Terraform configuration, set of variable values, state
|
|
data, run history, and settings.
|
|
|
|
These two kinds of workspaces are different, but related. When [using Terraform
|
|
CLI as a frontend for Terraform Cloud](/cli/cloud), you can associate the current working
|
|
directory with one or more remote workspaces. If you associate the
|
|
directory with multiple workspaces (using workspace tags), you can use the
|
|
`terraform workspace` commands to select which remote workspace to use.
|
|
|
|
Refer to [CLI-driven Runs](/cloud-docs/run/cli) in the Terraform Cloud documentation for more details about using Terraform CLI with Terraform Cloud.
|