• Overview
    • Enforce Policy as Code
    • Infrastructure as Code
    • Inject Secrets into Terraform
    • Integrate with Existing Workflows
    • Manage Kubernetes
    • Manage Virtual Machine Images
    • Multi-Cloud Deployment
    • Network Infrastructure Automation
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
  • Registry
  • Tutorials
    • About the Docs
    • Intro to Terraform
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
    • Terraform Tools
    • CDK for Terraform
    • Glossary
  • Community
GitHubTerraform Cloud
Download

    Terraform CLI

  • Overview
  • Basic CLI Features
    • Overview
    • init
    • get
    • Overview
    • plan
    • apply
    • destroy
    • Overview
    • login
    • logout
    • Overview
    • console
    • fmt
    • validate
    • 0.13upgrade
    • 0.12upgrade
    • Overview
    • graph
    • output
    • show
    • state list
    • state show
    • Overview
    • import
    • Usage Tips
    • Resource Importability
    • Overview
    • Resource Addressing
    • state
      • Overview
      • state list
      • state show
      • refresh
      • Overview
      • taint
      • untaint
      • Overview
      • state mv
      • state rm
      • state replace-provider
      • Overview
      • state pull
      • state push
      • force-unlock
    • Overview
      • Overview
      • workspace list
      • workspace select
      • workspace new
      • workspace delete
      • workspace show
    • Overview
    • Plugin Signing
    • providers
    • version
    • providers lock
    • providers mirror
    • providers schema
    • Overview
    • CLI Configuration
    • Environment Variables
    • Overview
    • Terraform Cloud Settings
    • Initializing and Migrating
    • Command Line Arguments
    • Running Terraform in Automation
    • GitHub Actions
    • Overview
    • apply
    • console
    • destroy
    • env
    • fmt
    • force-unlock
    • get
    • graph
    • import
    • init
    • login
    • logout
    • output
    • plan
    • providers
    • providers lock
    • providers mirror
    • providers schema
    • push (deprecated)
    • refresh
    • show
    • state
    • state list
    • state mv
    • state pull
    • state push
    • state replace-provider
    • state rm
    • state show
    • taint
    • test (deprecated)
    • untaint
    • validate
    • version
    • workspace
    • workspace list
    • workspace select
    • workspace new
    • workspace delete
    • workspace show
    • 0.12upgrade
    • 0.13upgrade
    • Overview
    • apply
    • console
    • destroy
    • env
    • fmt
    • force-unlock
    • get
    • graph
    • import
    • init
    • login
    • logout
    • output
    • plan
      • providers
      • providers lock
      • providers mirror
      • providers schema
    • push (deprecated)
    • refresh
    • show
      • state
      • state list
      • state mv
      • state pull
      • state push
      • state replace-provider
      • state rm
      • state show
    • taint
    • test (deprecated)
    • untaint
    • validate
    • version
      • workspace
      • workspace list
      • workspace select
      • workspace new
      • workspace delete
      • workspace show
    • 0.12upgrade
    • 0.13upgrade
    • APT Packages for Debian and Ubuntu
    • Yum Packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux

  • Terraform Internals

  • Other Docs

  • Intro to Terraform
  • Configuration Language
  • Terraform CLI
  • Terraform Cloud
  • Terraform Enterprise
  • Provider Use
  • Plugin Development
  • Registry Publishing
  • Integration Program
  • Terraform Tools
  • CDK for Terraform
  • Glossary
Type '/' to Search

»Managing Workspaces

In Terraform CLI, workspaces are separate instances of state data 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 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 and state manipulation commands) only interact with the currently selected workspace.
  • Use the terraform workspace select command to change the currently selected workspace.
  • Use the terraform workspace list, terraform workspace new, and terraform 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 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 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 (with different backend 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, 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 in the Terraform Cloud documentation for more details about using Terraform CLI with Terraform Cloud.

github logoEdit this page
  • Overview
  • Docs
  • Extend
  • Privacy
  • Security
  • Press Kit
  • Consent Manager