diff --git a/website/docs/state/workspaces.html.md b/website/docs/state/workspaces.html.md index 66738d3cd..fb9bed780 100644 --- a/website/docs/state/workspaces.html.md +++ b/website/docs/state/workspaces.html.md @@ -8,14 +8,20 @@ description: |- # Workspaces -A _workspace_ is a named container for Terraform state. With multiple -workspaces, a single directory of Terraform configuration can be used to -manage multiple distinct sets of infrastructure resources. +Each Terraform configuration has an associated [backend](/docs/backends/index.html) +that defines how operations are executed and where persistent data such as +[the Terraform state](https://www.terraform.io/docs/state/purpose.html) are +stored. -Terraform state determines what resources it manages based on what -exists in the state. This is how `terraform plan` determines what isn't -created, what needs to be updated, etc. The full details of state can be -found on [the _purpose_ page](/docs/state/purpose.html). +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 is still +has only one backend, but multiple distinct instances of that configuration +to be deployed without configuring a new backend or changing authentication +credentials. Multiple workspaces are currently supported by the following backends: @@ -89,37 +95,78 @@ resource "aws_instance" "example" { } ``` -## Best Practices +## When to use Multiple Workspaces -Workspaces can be used to manage small differences between development, -staging, and production, but they **should not** be treated as the only -isolation mechanism. As Terraform configurations get larger, it's much more -manageable and safer to split one large configuration into many -smaller ones linked together with the `terraform_remote_state` data source. -This allows teams to delegate ownership and reduce the potential impact of -changes. For *each* smaller configuration, you can use workspaces to model -the differences between development, staging, and production. However, if you -have one large Terraform configuration, it is riskier and not recommended to -use workspaces to handle those differences. +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. -[The `terraform_remote_state` data source](/docs/providers/terraform/d/remote_state.html) -accepts a `workspace` name to target. Therefore, you can link -together multiple independently managed Terraform configurations with the same -environment easily, with each configuration itself having multiple workspaces. +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. -While workspaces are available to all, -[Terraform Enterprise](https://www.hashicorp.com/products/terraform/) -provides an interface and API for managing sets of configurations linked -with `terraform_remote_state` and viewing them all as a single environment. +Non-default workspaces are often related to feature branches in version control. +The default workspace might correspond to the "master" 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. -Workspaces alone are useful for isolating a set of resources to test -changes during development. For example, it is common to associate a -branch in a VCS with a temporary workspace so new features can be developed -without affecting the default workspace. +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. -Future Terraform versions and workspace enhancements will enable -Terraform to track VCS branches with a workspace to help verify only certain -branches can make changes to a Terraform workspace. +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](/docs/modules/index.html) 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://consul.io/) cluster is available, use + [`consul_key_prefix`](/docs/providers/consul/r/key_prefix.html) to + publish to the key/value store and [`consul_keys`](/docs/providers/consul/d/keys.html) + 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](/docs/providers/aws/r/vpc.html) + to assign suitable tags and then + [the `aws_vpc` data source](/docs/providers/aws/d/vpc.html) + 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](/docs/providers/dns/index.html) 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`](/docs/providers/terraform/d/remote_state.html) + 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 @@ -129,7 +176,7 @@ 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 be treated similarly to -local-only `terraform.tfstate`); some teams commit these files to version +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.