From 7817e27992a767c2ffd532aa47a84fb333e87fd5 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Thu, 22 Sep 2022 22:50:08 +0000 Subject: [PATCH 1/9] backport of commit 6c34047efabdc598651a6d9608057f7230e6a19b --- website/docs/cli/workspaces/index.mdx | 147 ++++++++++++--------- website/docs/language/state/workspaces.mdx | 126 +----------------- 2 files changed, 91 insertions(+), 182 deletions(-) diff --git a/website/docs/cli/workspaces/index.mdx b/website/docs/cli/workspaces/index.mdx index 7a6b11f9e7c8..206f4799ec94 100644 --- a/website/docs/cli/workspaces/index.mdx +++ b/website/docs/cli/workspaces/index.mdx @@ -7,72 +7,97 @@ description: >- # 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. +Workspaces in the Terraform CLI refer to separate instances of [state data](/language/state) inside the same working directory. + +Terraform relies on state to associate resources with real-world objects. When you run the same configuration multiple times with separate state data, Terraform can manage multiple sets of non-overlapping resources. + +Workspaces let you create many instances of the same infrastructure or inject different [variable values](/language/values/variables) for each instance. For example, you may want to quickly create infrastructure to test changes without affecting the production deployment. + +## Managing CLI Workspaces + +Every [initialized working directory](/cli/init) starts with one workspace named `default`. + +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. + +Use [the `terraform workspace select` command](/cli/commands/workspace/select) to change the currently selected workspace. For a given working directory, you can only select one workspace can be at a time. Most Terraform commands only interact with the currently selected workspace. This includes [provisioning](/cli/run) and [state manipulation](/cli/state). ## Interactions with Terraform Cloud Workspaces Terraform Cloud organizes infrastructure using workspaces, but its workspaces -act more like completely separate working directories; each Terraform Cloud +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. +When you [integrate Terraform CLI with Terraform Cloud](/cli/cloud), you can associate the current CLI working directory with one or more remote Terraform Cloud workspaces. Then, use the `terraform workspace` commands to select the remote workspace you want to use for each run. + +Refer to [CLI-driven Runs](/cloud-docs/run/cli) in the Terraform Cloud documentation for more details. + +## Use Cases + +You can create multiple [working directories](/cli/init) to maintain multiple instances of a configuration with completely separate state data. However, Terraform 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 more 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 +feature branch is created to develop a change, the developer of that feature +might create a corresponding workspace and deploy into it a temporary copy +of the main infrastructure so that they can test changes 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 Terraform to manage larger systems, teams should create separate Terraform 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 is often specific to that deployment, with 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](/language/modules/develop) 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](/language/settings/backends/configuration). In that case, the root module of each configuration consists only of a backend configuration and a small number of `module` blocks whose arguments describe 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. + +- When a shared [Consul](https://www.consul.io/) cluster is available, use + [`consul_key_prefix`](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/resources/key_prefix) to + publish to the key/value store and [`consul_keys`](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/data-sources/keys) + to retrieve those values in other configurations. + +- 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](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc) + to assign suitable tags and then + [the `aws_vpc` data source](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/vpc) + 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 and then either use that name directly or + use [the `dns` provider](https://registry.terraform.io/providers/hashicorp/dns/latest/docs) to retrieve + the published addresses in other configurations. + +- If a Terraform state for one configuration is stored in a remote backend + that is accessible to other configurations then + [`terraform_remote_state`](/language/state/remote-state-data) + can be used to directly consume its root module outputs from those other + configurations. This creates a tighter coupling between configurations, + but avoids the need for the "producer" configuration to explicitly + publish its results in a separate system. + + +## Workspace Internals + +Workspaces are technically equivalent to renaming your state file. Terraform 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, Terraform 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](/language/state/remote), the workspaces are stored directly in the configured [backend](/language/settings/backends). For example, if you use [Consul](/language/settings/backends/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. -Refer to [CLI-driven Runs](/cloud-docs/run/cli) in the Terraform Cloud documentation for more details about using Terraform CLI with Terraform Cloud. +The current workspace name is stored 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 Terraform Cloud. For more details about workspace names in Terraform Cloud, refer to the [CLI Integration (recommended)](/cli/cloud/settings#arguments) and [remote backend](/language/settings/backends/remote#workspaces) and documentation. \ No newline at end of file diff --git a/website/docs/language/state/workspaces.mdx b/website/docs/language/state/workspaces.mdx index ecb3421751e6..a16f81712293 100644 --- a/website/docs/language/state/workspaces.mdx +++ b/website/docs/language/state/workspaces.mdx @@ -16,7 +16,7 @@ The persistent data stored in the backend belongs to a _workspace_. Initially the backend has only one workspace, called "default", and thus there is only one Terraform state associated with that configuration. -Certain backends support _multiple_ named workspaces, allowing multiple states +Certain backends support multiple named workspaces, allowing multiple states to be associated with a single configuration. The configuration still has only one backend, but multiple distinct instances of that configuration to be deployed without configuring a new backend or changing authentication @@ -48,30 +48,14 @@ and are migrating that configuration to Terraform Cloud, refer to [Initializing ## Using Workspaces -Terraform starts with a single workspace named "default". This -workspace is special both because it is the default and also because -it cannot ever be deleted. If you've never explicitly used workspaces, then -you've only ever worked on the "default" workspace. +~> **Important:** Workspaces are convenient, but they are not appropriate for system decomposition or deployments requiring separate credentials and access controls. Refer to [When Not to Use Multiple Workspaces](/cli/workspaces#when-not-to-use-multiple-workspaces) in the Terraform CLI documentation for details and recommended alternatives. -Workspaces are managed with the `terraform workspace` set of commands. To -create a new workspace and switch to it, you can use `terraform workspace new`; -to switch workspaces you can use `terraform workspace select`; etc. +Terraform starts with a single, default workspace named `default` that you cannot delete. If you have never created a new workspace, you use the `default` workspace in your Terraform working directory. -For example, creating a new workspace: +When you run `terraform plan` in a new workspace, Terraform does not access existing resources in any other workspace. These resources still physically exist, but you must switch workspaces to manage them. -```text -$ terraform workspace new bar -Created and switched to workspace "bar"! +You can manage workspaces with the `terraform workspace` set of commands. Refer to the [Terraform CLI workspaces](/cli/workspaces) documentation for more details. -You're now on a new, empty workspace. Workspaces isolate their state, -so if you run "terraform plan" Terraform will not see any existing state -for this configuration. -``` - -As the command says, if you run `terraform plan`, Terraform will not see -any existing resources that existed on the default (or any other) workspace. -**These resources still physically exist,** but are managed in another -Terraform workspace. ## Current Workspace Interpolation @@ -103,103 +87,3 @@ resource "aws_instance" "example" { # ... other arguments } ``` - -## When to use Multiple Workspaces - -Named workspaces allow conveniently switching between multiple instances of -a _single_ configuration within its _single_ backend. They are convenient in -a number of situations, but cannot solve all problems. - -A common use for multiple workspaces is to create a parallel, distinct copy of -a set of infrastructure in order to test a set of changes before modifying the -main production infrastructure. For example, a developer working on a complex -set of infrastructure changes might create a new temporary workspace in order -to freely experiment with changes without affecting the default workspace. - -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 -feature branch is created to develop a change, the developer of that feature -might create a corresponding workspace and deploy into it a temporary "copy" -of the main infrastructure so that changes can be tested without affecting -the production infrastructure. Once the change is merged and deployed to the -default workspace, the test infrastructure can be destroyed and the temporary -workspace deleted. - -When Terraform is used to manage larger systems, teams should use multiple -separate Terraform configurations that correspond with suitable architectural -boundaries within the system so that different components can be managed -separately and, if appropriate, by distinct teams. Workspaces _alone_ -are not a suitable tool for system decomposition, because each subsystem should -have its own separate configuration and backend, and will thus have its own -distinct set of workspaces. - -In particular, organizations commonly want to create a strong separation -between multiple deployments of the same infrastructure serving different -development stages (e.g. staging vs. production) or different internal teams. -In this case, the backend used for each deployment often belongs to that -deployment, with different credentials and access controls. Named workspaces -are _not_ a suitable isolation mechanism for this scenario. - -Instead, use one or more [re-usable modules](/language/modules/develop) 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. In that case, the root module of each configuration will -consist only of a backend configuration and a small number of `module` blocks -whose arguments describe any small differences between the deployments. - -Where multiple configurations are representing distinct system components -rather than multiple deployments, data can be passed from one component to -another using paired resources types and data sources. For example: - -* Where a shared [Consul](https://www.consul.io/) cluster is available, use - [`consul_key_prefix`](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/resources/key_prefix) to - publish to the key/value store and [`consul_keys`](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/data-sources/keys) - to retrieve those values in other configurations. - -* 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](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc) - to assign suitable tags and then - [the `aws_vpc` data source](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/vpc) - 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 and then either use that name directly or - use [the `dns` provider](https://registry.terraform.io/providers/hashicorp/dns/latest/docs) to retrieve - the published addresses in other configurations. - -* If a Terraform state for one configuration is stored in a remote backend - that is accessible to other configurations then - [`terraform_remote_state`](/language/state/remote-state-data) - can be used to directly consume its root module outputs from those other - configurations. This creates a tighter coupling between configurations, - but avoids the need for the "producer" configuration to explicitly - publish its results in a separate system. - -## Workspace Internals - -Workspaces are technically equivalent to renaming your state file. They -aren't any more complex than that. Terraform wraps this simple notion with -a set of protections and support for remote state. - -For local state, Terraform 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, although using a remote backend instead is recommended when there are -multiple collaborators. - -For [remote state](/language/state/remote), the workspaces are stored -directly in the configured [backend](/language/settings/backends). For example, if you -use [Consul](/language/settings/backends/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. - -The important thing about workspace internals is that workspaces are -meant to be a shared resource. They aren't a private, local-only notion -(unless you're using purely local state and not committing it). - -The "current workspace" name is stored 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 Terraform Cloud. For more details about workspace names in Terraform Cloud, refer to the [remote backend](/language/settings/backends/remote#workspaces) and [CLI Integration (recommended)](/cli/cloud/settings#arguments) documentation. From 0e7161851152b4d30d1a68152e1903bd02239af7 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Thu, 22 Sep 2022 23:03:42 +0000 Subject: [PATCH 2/9] backport of commit 2fc8289cf12e7f18fef953378a9053acc121bdc2 --- website/docs/language/state/workspaces.mdx | 61 ++++++++-------------- 1 file changed, 23 insertions(+), 38 deletions(-) diff --git a/website/docs/language/state/workspaces.mdx b/website/docs/language/state/workspaces.mdx index a16f81712293..1fb70a1a8648 100644 --- a/website/docs/language/state/workspaces.mdx +++ b/website/docs/language/state/workspaces.mdx @@ -7,54 +7,39 @@ description: >- # Workspaces -Each Terraform configuration has an associated [backend](/language/settings/backends) -that defines how operations are executed and where persistent data such as -[the Terraform state](/language/state/purpose) are +Each Terraform configuration has an associated [backend](/language/settings/backends) that defines how operations are executed and where persistent data such as [the Terraform state](/language/state/purpose) are stored. -The persistent data stored in the backend belongs to a _workspace_. Initially -the backend has only one workspace, called "default", and thus there is only -one Terraform state associated with that configuration. - -Certain backends support multiple named workspaces, allowing multiple states -to be associated with a single configuration. The configuration still -has only one backend, but multiple distinct instances of that configuration -to be deployed without configuring a new backend or changing authentication +The persistent data stored in the backend belongs to a workspace. The backend initially has only one workspace containing one Terraform 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. -Multiple workspaces are currently supported by the following backends: - -* [AzureRM](/language/settings/backends/azurerm) -* [Consul](/language/settings/backends/consul) -* [COS](/language/settings/backends/cos) -* [GCS](/language/settings/backends/gcs) -* [Kubernetes](/language/settings/backends/kubernetes) -* [Local](/language/settings/backends/local) -* [OSS](/language/settings/backends/oss) -* [Postgres](/language/settings/backends/pg) -* [Remote](/language/settings/backends/remote) -* [S3](/language/settings/backends/s3) - -In the 0.9 line of Terraform releases, this concept was known as "environment". -It was renamed in 0.10 based on feedback about confusion caused by the -overloading of the word "environment" both within Terraform itself and within -organizations that use Terraform. - --> **Note**: The Terraform CLI workspace concept described in this document is -different from but related to the Terraform Cloud -[workspace](/cloud-docs/workspaces) concept. -If you use multiple Terraform CLI workspaces in a single Terraform configuration -and are migrating that configuration to Terraform Cloud, refer to [Initializing and Migrating](/cli/cloud/migrating). +-> **Note**: The Terraform CLI workspaces are different from [workspaces in Terraform Cloud](/cloud-docs/workspaces). Refer to [Initializing and Migrating](/cli/cloud/migrating) for details about migrating a configuration with multiple workspaces to Terraform Cloud. + +## Backends Supporting Multiple Workspaces + +The following backends support multiple workspaces: + +- [AzureRM](/language/settings/backends/azurerm) +- [Consul](/language/settings/backends/consul) +- [COS](/language/settings/backends/cos) +- [GCS](/language/settings/backends/gcs) +- [Kubernetes](/language/settings/backends/kubernetes) +- [Local](/language/settings/backends/local) +- [OSS](/language/settings/backends/oss) +- [Postgres](/language/settings/backends/pg) +- [Remote](/language/settings/backends/remote) +- [S3](/language/settings/backends/s3) + ## Using Workspaces -~> **Important:** Workspaces are convenient, but they are not appropriate for system decomposition or deployments requiring separate credentials and access controls. Refer to [When Not to Use Multiple Workspaces](/cli/workspaces#when-not-to-use-multiple-workspaces) in the Terraform CLI documentation for details and recommended alternatives. +~> **Important:** Workspaces are not appropriate for system decomposition or deployments requiring separate credentials and access controls. Refer to [When Not to Use Multiple Workspaces](/cli/workspaces#when-not-to-use-multiple-workspaces) in the Terraform CLI documentation for details and recommended alternatives. -Terraform starts with a single, default workspace named `default` that you cannot delete. If you have never created a new workspace, you use the `default` workspace in your Terraform working directory. +Terraform 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 Terraform working directory. -When you run `terraform plan` in a new workspace, Terraform does not access existing resources in any other workspace. These resources still physically exist, but you must switch workspaces to manage them. +When you run `terraform plan` in a new workspace, Terraform does not access existing resources in other workspaces. These resources still physically exist, but you must switch workspaces to manage them. -You can manage workspaces with the `terraform workspace` set of commands. Refer to the [Terraform CLI workspaces](/cli/workspaces) documentation for more details. +Refer to the [Terraform CLI workspaces](/cli/workspaces) documentation for full details about how to create and use workspaces. ## Current Workspace Interpolation From 1b05bb3e420f52ee50d955df050c655666e2bfaf Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Thu, 22 Sep 2022 23:07:55 +0000 Subject: [PATCH 3/9] backport of commit 35a5e926872dbddd14de999de2e2b6bace80cd15 --- website/docs/language/state/workspaces.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/language/state/workspaces.mdx b/website/docs/language/state/workspaces.mdx index 1fb70a1a8648..1e5623822bdb 100644 --- a/website/docs/language/state/workspaces.mdx +++ b/website/docs/language/state/workspaces.mdx @@ -17,7 +17,7 @@ credentials. ## Backends Supporting Multiple Workspaces -The following backends support multiple workspaces: +You can use multiple workspaces with the following backends: - [AzureRM](/language/settings/backends/azurerm) - [Consul](/language/settings/backends/consul) From 6ec86aad76eedde4bf9076ccf426e13755ca9f07 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Thu, 22 Sep 2022 23:11:14 +0000 Subject: [PATCH 4/9] backport of commit f7bf19525e180b1c40ca782028c06fabcad73cae --- website/docs/cli/workspaces/index.mdx | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/website/docs/cli/workspaces/index.mdx b/website/docs/cli/workspaces/index.mdx index 206f4799ec94..66c8accce414 100644 --- a/website/docs/cli/workspaces/index.mdx +++ b/website/docs/cli/workspaces/index.mdx @@ -21,16 +21,6 @@ Use the [`terraform workspace list`](/cli/commands/workspace/list), [`terraform Use [the `terraform workspace select` command](/cli/commands/workspace/select) to change the currently selected workspace. For a given working directory, you can only select one workspace can be at a time. Most Terraform commands only interact with the currently selected workspace. This includes [provisioning](/cli/run) and [state manipulation](/cli/state). -## 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. - -When you [integrate Terraform CLI with Terraform Cloud](/cli/cloud), you can associate the current CLI working directory with one or more remote Terraform Cloud workspaces. Then, use the `terraform workspace` commands to select the remote workspace you want to use for each run. - -Refer to [CLI-driven Runs](/cloud-docs/run/cli) in the Terraform Cloud documentation for more details. ## Use Cases @@ -88,6 +78,18 @@ When multiple configurations represent distinct system components rather than mu configurations. This creates a tighter coupling between configurations, but avoids the need for the "producer" configuration to explicitly publish its results in a separate system. + + +## 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. + +When you [integrate Terraform CLI with Terraform Cloud](/cli/cloud), you can associate the current CLI working directory with one or more remote Terraform Cloud workspaces. Then, use the `terraform workspace` commands to select the remote workspace you want to use for each run. + +Refer to [CLI-driven Runs](/cloud-docs/run/cli) in the Terraform Cloud documentation for more details. ## Workspace Internals From ea65b31a495969f963361e6c8d5c3330cbfaa545 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Fri, 23 Sep 2022 20:32:15 +0000 Subject: [PATCH 5/9] backport of commit 94eed2c45b781bc7cf42f578cbff084f6e13ea49 --- website/docs/cli/workspaces/index.mdx | 59 +++++++++------------------ 1 file changed, 20 insertions(+), 39 deletions(-) diff --git a/website/docs/cli/workspaces/index.mdx b/website/docs/cli/workspaces/index.mdx index 66c8accce414..a5b84fe65b18 100644 --- a/website/docs/cli/workspaces/index.mdx +++ b/website/docs/cli/workspaces/index.mdx @@ -7,11 +7,12 @@ description: >- # Managing Workspaces -Workspaces in the Terraform CLI refer to separate instances of [state data](/language/state) inside the same working directory. +Workspaces in the Terraform CLI refer to separate instances of [state data](/language/state) inside the same Terraform working directory. They are distinctly different from [workspaces in Terraform Cloud](/cloud-docs/workspaces), which each have their own Terraform configuration and function as separate working directories. Terraform relies on state to associate resources with real-world objects. When you run the same configuration multiple times with separate state data, Terraform can manage multiple sets of non-overlapping resources. -Workspaces let you create many instances of the same infrastructure or inject different [variable values](/language/values/variables) for each instance. For example, you may want to quickly create infrastructure to test changes without affecting the production deployment. +Workspaces can be helpful for specific [use cases](#use-cases), but they are not required to use the Terraform CLI. We recommend using [alternative approaches](#alternatives-to-workspaces) for complex deployments requiring separate credentials and access controls. + ## Managing CLI Workspaces @@ -21,64 +22,44 @@ Use the [`terraform workspace list`](/cli/commands/workspace/list), [`terraform Use [the `terraform workspace select` command](/cli/commands/workspace/select) to change the currently selected workspace. For a given working directory, you can only select one workspace can be at a time. Most Terraform commands only interact with the currently selected workspace. This includes [provisioning](/cli/run) and [state manipulation](/cli/state). +When you provision infrastructure in each workspace, you usually need to manually specify different [input variables](/language/values/variables) to differentiate each collection. For example, you might deploy test infrastructure to a different region. + ## Use Cases -You can create multiple [working directories](/cli/init) to maintain multiple instances of a configuration with completely separate state data. However, Terraform 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 more 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. +You can create multiple [working directories](/cli/init) to maintain multiple instances of a configuration with completely separate state data. However, Terraform 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 -feature branch is created to develop a change, the developer of that feature -might create a corresponding workspace and deploy into it a temporary copy -of the main infrastructure so that they can test changes 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. +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 Terraform to manage larger systems, teams should create separate Terraform 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. +When using Terraform to manage larger systems, you should create separate Terraform 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 is often specific to that deployment, with 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. +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](/language/modules/develop) 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](/language/settings/backends/configuration). In that case, the root module of each configuration consists only of a backend configuration and a small number of `module` blocks whose arguments describe any small differences between the deployments. +Instead of creating CLI workspaces, you can use one or more [re-usable modules](/language/modules/develop) 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](/language/settings/backends/configuration). 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. -- When a shared [Consul](https://www.consul.io/) cluster is available, use - [`consul_key_prefix`](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/resources/key_prefix) to - publish to the key/value store and [`consul_keys`](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/data-sources/keys) - to retrieve those values in other configurations. - -- 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](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc) - to assign suitable tags and then - [the `aws_vpc` data source](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/vpc) - 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 and then either use that name directly or - use [the `dns` provider](https://registry.terraform.io/providers/hashicorp/dns/latest/docs) to retrieve - the published addresses in other configurations. - -- If a Terraform state for one configuration is stored in a remote backend - that is accessible to other configurations then - [`terraform_remote_state`](/language/state/remote-state-data) - can be used to directly consume its root module outputs from those other - configurations. This creates a tighter coupling between configurations, - but avoids the need for the "producer" configuration to explicitly - publish its results in a separate system. - +- When a shared [Consul](https://www.consul.io/) cluster is available, use [`consul_key_prefix`](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/resources/key_prefix) to publish to the key/value store and [`consul_keys`](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/data-sources/keys) to retrieve those values in other configurations. + +- 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](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc) to assign suitable tags and then [the `aws_vpc` data source](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/vpc) 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](https://registry.terraform.io/providers/hashicorp/dns/latest/docs) to retrieve the published addresses in other configurations. + +- If you store a Terraform state for one configuration in a remote backend that other configurations can access, then the other configurations can use [`terraform_remote_state`](/language/state/remote-state-data) 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. + ## Interactions with Terraform Cloud Workspaces @@ -102,4 +83,4 @@ For local state, Terraform stores the workspace states in a directory called `te For [remote state](/language/state/remote), the workspaces are stored directly in the configured [backend](/language/settings/backends). For example, if you use [Consul](/language/settings/backends/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. -The current workspace name is stored 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 Terraform Cloud. For more details about workspace names in Terraform Cloud, refer to the [CLI Integration (recommended)](/cli/cloud/settings#arguments) and [remote backend](/language/settings/backends/remote#workspaces) and documentation. \ No newline at end of file +Terraform 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 Terraform Cloud. For more details about workspace names in Terraform Cloud, refer to the [CLI Integration (recommended)](/cli/cloud/settings#arguments) and [remote backend](/language/settings/backends/remote#workspaces) and documentation. \ No newline at end of file From 656f862aced48dda92ee29ba45d6c25afafc6e4f Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Fri, 23 Sep 2022 21:17:06 +0000 Subject: [PATCH 6/9] backport of commit 776c25777d47bf0248b8f4b4c82c75744d4e5034 --- website/docs/language/state/workspaces.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/language/state/workspaces.mdx b/website/docs/language/state/workspaces.mdx index 1e5623822bdb..bec31346fc21 100644 --- a/website/docs/language/state/workspaces.mdx +++ b/website/docs/language/state/workspaces.mdx @@ -33,7 +33,7 @@ You can use multiple workspaces with the following backends: ## Using Workspaces -~> **Important:** Workspaces are not appropriate for system decomposition or deployments requiring separate credentials and access controls. Refer to [When Not to Use Multiple Workspaces](/cli/workspaces#when-not-to-use-multiple-workspaces) in the Terraform CLI documentation for details and recommended alternatives. +~> **Important:** Workspaces are not appropriate for system decomposition or deployments requiring separate credentials and access controls. Refer to [Use Cases](/cli/workspaces#use-cases) in the Terraform CLI documentation for details and recommended alternatives. Terraform 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 Terraform working directory. From b2a03e9826ce325011abcdee480ef6255feb63ef Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Fri, 23 Sep 2022 21:24:39 +0000 Subject: [PATCH 7/9] backport of commit 6753fb5476a9eaf016118aacb4c63e5c5e8cd8cc --- website/docs/language/state/workspaces.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/language/state/workspaces.mdx b/website/docs/language/state/workspaces.mdx index bec31346fc21..4610961445d3 100644 --- a/website/docs/language/state/workspaces.mdx +++ b/website/docs/language/state/workspaces.mdx @@ -7,7 +7,7 @@ description: >- # Workspaces -Each Terraform configuration has an associated [backend](/language/settings/backends) that defines how operations are executed and where persistent data such as [the Terraform state](/language/state/purpose) are +Each Terraform configuration has an associated [backend](/language/settings/backends) that defines how Terraform executes operations where Terraform stores persistent data, like [Terraform state](/language/state/purpose). stored. The persistent data stored in the backend belongs to a workspace. The backend initially has only one workspace containing one Terraform 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 From ebe95bc2e382c19fd3451e4f27888949cdc1ae0a Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Fri, 23 Sep 2022 21:24:54 +0000 Subject: [PATCH 8/9] backport of commit 2ea3765fa68a492b54a53f197c4d1b50df500cbc --- website/docs/language/state/workspaces.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/website/docs/language/state/workspaces.mdx b/website/docs/language/state/workspaces.mdx index 4610961445d3..73db3c349c55 100644 --- a/website/docs/language/state/workspaces.mdx +++ b/website/docs/language/state/workspaces.mdx @@ -8,7 +8,6 @@ description: >- # Workspaces Each Terraform configuration has an associated [backend](/language/settings/backends) that defines how Terraform executes operations where Terraform stores persistent data, like [Terraform state](/language/state/purpose). -stored. The persistent data stored in the backend belongs to a workspace. The backend initially has only one workspace containing one Terraform 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. From 3d0bbe5096750f5dc3a7c044b51d507d12996ccc Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Fri, 23 Sep 2022 21:25:24 +0000 Subject: [PATCH 9/9] backport of commit 0471c80ebe99ebf9b6e1f5cf422d06baeff3f5f9 --- website/docs/language/state/workspaces.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/language/state/workspaces.mdx b/website/docs/language/state/workspaces.mdx index 73db3c349c55..ab8a659c8f46 100644 --- a/website/docs/language/state/workspaces.mdx +++ b/website/docs/language/state/workspaces.mdx @@ -7,7 +7,7 @@ description: >- # Workspaces -Each Terraform configuration has an associated [backend](/language/settings/backends) that defines how Terraform executes operations where Terraform stores persistent data, like [Terraform state](/language/state/purpose). +Each Terraform configuration has an associated [backend](/language/settings/backends) that defines how Terraform executes operations and where Terraform stores persistent data, like [state](/language/state/purpose). The persistent data stored in the backend belongs to a workspace. The backend initially has only one workspace containing one Terraform 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.