github.com/iaas-resource-provision/iaas-rpc@v1.0.7-0.20211021023331-ed21f798c408/website/docs/cli/workspaces/index.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Managing Workspaces - Terraform CLI"
     4  description: "Commands to list, select, create, and output workspaces. Workspaces help manage different groups of resources with one configuration."
     5  ---
     6  
     7  # Managing Workspaces
     8  
     9  In Terraform CLI, _workspaces_ are separate instances of
    10  [state data](/docs/language/state/index.html) that can be used from the same working
    11  directory. You can use workspaces to manage multiple non-overlapping groups of
    12  resources with the same configuration.
    13  
    14  - Every [initialized working directory](/docs/cli/init/index.html) has at least
    15    one workspace. (If you haven't created other workspaces, it is a workspace
    16    named `default`.)
    17  - For a given working directory, only one workspace can be _selected_ at a time.
    18  - Most Terraform commands (including [provisioning](/docs/cli/run/index.html)
    19    and [state manipulation](/docs/cli/state/index.html) commands) only interact
    20    with the currently selected workspace.
    21  - Use [the `terraform workspace select` command](/docs/cli/commands/workspace/select.html)
    22    to change the currently selected workspace.
    23  - Use the [`terraform workspace list`](/docs/cli/commands/workspace/list.html),
    24    [`terraform workspace new`](/docs/cli/commands/workspace/new.html), and
    25    [`terraform workspace delete`](/docs/cli/commands/workspace/delete.html) commands
    26    to manage the available workspaces in the current working directory.
    27  
    28  -> **Note:** Terraform Cloud and Terraform CLI both have features called
    29  "workspaces," but they're slightly different. Terraform Cloud's workspaces
    30  behave more like completely separate working directories.
    31  
    32  ## The Purpose of Workspaces
    33  
    34  Since most of the resources you can manage with Terraform don't include a unique
    35  name as part of their configuration, it's common to use the same Terraform
    36  configuration to provision multiple groups of similar resources.
    37  
    38  Terraform relies on [state](/docs/language/state/index.html) to associate resources with
    39  real-world objects, so if you run the same configuration multiple times with
    40  completely separate state data, Terraform can manage many non-overlapping groups
    41  of resources. In some cases you'll want to change
    42  [variable values](/docs/language/values/variables.html) for these different
    43  resource collections (like when specifying differences between staging and
    44  production deployments), and in other cases you might just want many instances
    45  of a particular infrastructure pattern.
    46  
    47  The simplest way to maintain multiple instances of a configuration with
    48  completely separate state data is to use multiple
    49  [working directories](/docs/cli/init/index.html) (with different
    50  [backend](/docs/language/settings/backends/configuration.html) configurations per directory, if you
    51  aren't using the default `local` backend).
    52  
    53  However, this isn't always the most _convenient_ way to handle separate states.
    54  Terraform installs a separate cache of plugins and modules for each working
    55  directory, so maintaining multiple directories can waste bandwidth and disk
    56  space. You must also update your configuration code from version control
    57  separately for each directory, reinitialize each directory separately when
    58  changing the configuration, etc.
    59  
    60  Workspaces allow you to use the same working copy of your configuration and the
    61  same plugin and module caches, while still keeping separate states for each
    62  collection of resources you manage.
    63  
    64  ## Interactions with Terraform Cloud Workspaces
    65  
    66  Terraform Cloud organizes infrastructure using workspaces, but its workspaces
    67  act more like completely separate working directories; each Terraform Cloud
    68  workspace has its own Terraform configuration, set of variable values, state
    69  data, run history, and settings.
    70  
    71  These two kinds of workspaces are different, but related. When using Terraform
    72  CLI as a frontend for Terraform Cloud, you associate the current working
    73  directory with one or more remote workspaces by configuring
    74  [the `remote` backend](/docs/language/settings/backends/remote.html). If you associate the
    75  directory with multiple workspaces (using a name prefix), you can use the
    76  `terraform workspace` commands to select which remote workspace to use.
    77  
    78  For more information about using Terraform CLI with Terraform Cloud, see
    79  [CLI-driven Runs](/docs/cloud/run/cli.html) in the Terraform Cloud docs.