IntenseWebs/opentofu
3
0
Fork 0
mirror of https://github.com/opentofu/opentofu.git synced 2024-12-28 01:41:48 -06:00
Code Issues Packages Projects Releases Wiki Activity

website: Clarify workspace concepts for remote backend

Browse Source 
There are some differences between the Terraform CLI and Terraform Cloud ideas of workspaces.

This documentation aims to explain those differences and show different patterns for configuring the remote backend and the implications of different approaches.
This commit is contained in:
Roger Berlind 2019-11-06 20:03:20 -05:00 committed by Martin Atkins
parent dbff07c841
commit de4ef9c546
2 changed files with 52 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
website/docs/backends/types/remote.html.md
View File

@ -49,30 +49,49 @@ Currently the remote backend supports the following Terraform commands:
## Workspaces ## Workspaces
The remote backend can work with either a single remote workspace, or with The remote backend can work with either a single remote Terraform Cloud workspace,
multiple similarly-named remote workspaces (like `networking-dev` and or with multiple similarly-named remote workspaces (like `networking-dev`
`networking-prod`). The `workspaces` block of the backend configuration and `networking-prod`). The `workspaces` block of the backend configuration
determines which mode it uses: determines which mode it uses:
- To use a single workspace, set `workspaces.name` to the remote workspace's - To use a single remote Terraform Cloud workspace, set `workspaces.name` to the
full name (like `networking`). remote workspace's full name (like `networking`).
- To use multiple workspaces, set `workspaces.prefix` to a prefix used in - To use multiple remote workspaces, set `workspaces.prefix` to a prefix used in
all of the desired remote workspace names. For example, set all of the desired remote workspace names. For example, set
`prefix = "networking-"` to use a group of workspaces with names like `prefix = "networking-"` to use Terraform cloud workspaces with
`networking-dev` and `networking-prod`. names like `networking-dev` and `networking-prod`. This is helpful when
mapping multiple Terraform CLI [workspaces](../../state/workspaces.html)
used in a single Terraform configuration to multiple Terraform Cloud
workspaces.
When interacting with workspaces on the command line, Terraform uses When interacting with workspaces on the command line, Terraform uses
shortened names without the common prefix. For example, if shortened names without the common prefix. For example, if
`prefix = "networking-"`, use `terraform workspace select prod` to switch to `prefix = "networking-"`, use `terraform workspace select prod` to switch to
the `networking-prod` workspace. the Terraform CLI workspace `prod` within the current configuration. Remote
Terraform operations such as `plan` and `apply` executed against that Terraform
CLI workspace will be executed in the Terraform Cloud workspace `networking-prod`.
Additionally, the [`${terraform.workspace}`](../../state/workspaces.html#current-workspace-interpolation)
interpolation sequence should be removed from Terraform configurations that run
remote operations against Terraform Cloud workspaces. The reason for this is that
each Terraform Cloud workspace currently only uses the single `default` Terraform
CLI workspace internally. In other words, if your Terraform configuration
used `${terraform.workspace}` to return `dev` or `prod`, remote runs in Terraform Cloud
would always evaluate it as `default` regardless of
which workspace you had set with the `terraform workspace select` command. That
would most likely not be what you wanted. (It is ok to use `${terraform.workspace}`
in local operations.)
The backend configuration requires either `name` or `prefix`. Omitting both or The backend configuration requires either `name` or `prefix`. Omitting both or
setting both results in a configuration error. setting both results in a configuration error.
If previous state is present when you run `terraform init` and the corresponding If previous state is present when you run `terraform init` and the corresponding
remote workspaces are empty or absent, Terraform will create workspaces and/or remote workspaces are empty or absent, Terraform will create workspaces and/or
update the remote state accordingly. update the remote state accordingly. However, if your workspace needs variables
set or requires a specific version of Terraform for remote operations, we
recommend that you create your remote workspaces on Terraform Cloud before
running any remote operations against them.
## Example Configuration ## Example Configuration
@ -164,8 +183,12 @@ The following configuration options are supported:
* `prefix` - (Optional) A prefix used in the names of one or more remote * `prefix` - (Optional) A prefix used in the names of one or more remote
workspaces, all of which can be used with this configuration. The full workspaces, all of which can be used with this configuration. The full
workspace names are used in Terraform Cloud, and the short names workspace names are used in Terraform Cloud, and the short names
(minus the prefix) are used on the command line. If omitted, only the (minus the prefix) are used on the command line for Terraform CLI workspaces.
default workspace can be used. This option conflicts with `name`. If omitted, only the default workspace can be used. This option conflicts with `name`.
-> **Note** You must use the `name` key when configuring a `terraform_remote_state`
data source that retrieves state from another Terraform Cloud workspace. The `prefix` key is only
intended for use when configuring an instance of the remote backend.
## Excluding Files from Upload with .terraformignore ## Excluding Files from Upload with .terraformignore

16
website/docs/state/workspaces.html.md
View File

@ -39,6 +39,13 @@ 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 overloading of the word "environment" both within Terraform itself and within
organizations that use Terraform. organizations that use Terraform.
-> **Note**: The Terraform CLI workspace concept described in this document is
different from but related to the Terraform Cloud
[workspace](/docs/cloud/workspaces/index.html) concept.
If you use multiple Terraform CLI workspaces in a single Terraform configuration
and are migrating that configuration to Terraform Cloud, see this [migration
document](/docs/cloud/migrate/workspaces.html).
## Using Workspaces ## Using Workspaces
Terraform starts with a single workspace named "default". This Terraform starts with a single workspace named "default". This
@ -70,7 +77,10 @@ Terraform workspace.
Within your Terraform configuration, you may include the name of the current Within your Terraform configuration, you may include the name of the current
workspace using the `${terraform.workspace}` interpolation sequence. This can workspace using the `${terraform.workspace}` interpolation sequence. This can
be used anywhere interpolations are allowed. be used anywhere interpolations are allowed. However, it should **not** be
used in remote operations against Terraform Cloud workspaces. For an
explanation, see the [remote backend](../backends/types/remote.html#workspaces)
document.
Referencing the current workspace is useful for changing behavior based Referencing the current workspace is useful for changing behavior based
on the workspace. For example, for non-default workspaces, it may be useful on the workspace. For example, for non-default workspaces, it may be useful
@ -195,4 +205,6 @@ meant to be a shared resource. They aren't a private, local-only notion
The "current workspace" name is stored only locally in the ignored The "current workspace" name is stored only locally in the ignored
`.terraform` directory. This allows multiple team members to work on `.terraform` directory. This allows multiple team members to work on
different workspaces concurrently. different workspaces concurrently. The "current workspace" name is **not**
currently meaningful in Terraform Cloud workspaces since it will always
have the value `default`.