From ba0e2c1133f0ec26445aa478fada1897e2311e20 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Wed, 9 Feb 2022 14:10:11 -0500 Subject: [PATCH 1/5] Update remote backend page to clarify workspace.name expression --- .../language/settings/backends/remote.mdx | 60 +++++++++++-------- 1 file changed, 36 insertions(+), 24 deletions(-) diff --git a/website/docs/language/settings/backends/remote.mdx b/website/docs/language/settings/backends/remote.mdx index e67c90e27..d15fd2162 100644 --- a/website/docs/language/settings/backends/remote.mdx +++ b/website/docs/language/settings/backends/remote.mdx @@ -14,7 +14,7 @@ The remote backend is unique among all other Terraform backends because it can b When using full remote operations, operations like `terraform plan` or `terraform apply` can be executed in Terraform Cloud's run environment, with log output streaming to the local terminal. Remote plans and applies use variable values from the associated Terraform Cloud workspace. -Terraform Cloud can also be used with local operations, in which case only state is stored in the Terraform Cloud backend. +You can also use Terraform Cloud with local operations, in which case only state is stored in the Terraform Cloud backend. ## Command Support @@ -41,9 +41,7 @@ Currently the remote backend supports the following Terraform commands: ## Workspaces -The remote backend can work with either a single remote Terraform Cloud workspace, -or with multiple similarly-named remote workspaces (like `networking-dev` -and `networking-prod`). The `workspaces` block of the backend configuration +The remote backend can work with either a single remote Terraform Cloud workspace, or with multiple similarly-named remote workspaces (like `networking-dev` and `networking-prod`). The `workspaces` block of the backend configuration determines which mode it uses: - To use a single remote Terraform Cloud workspace, set `workspaces.name` to the @@ -57,34 +55,48 @@ determines which mode it uses: used in a single Terraform configuration to multiple Terraform Cloud workspaces. -When interacting with workspaces on the command line, Terraform uses -shortened names without the common prefix. For example, if -`prefix = "networking-"`, use `terraform workspace select prod` to switch to -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`](/language/state/workspaces#current-workspace-interpolation) -expression shouldn't be used in Terraform configurations that use Terraform 1.0.x or earlier and run -remote operations against Terraform Cloud workspaces. The reason for this is that -prior to Terraform 1.1.0, Terraform Cloud workspaces only used 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, and with remote operations in workspaces configured to use Terraform 1.1.0 or later.) The backend configuration requires either `name` or `prefix`. Omitting both or setting both results in a configuration error. 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 -update the remote state accordingly. However, if your workspace needs variables -set or requires a specific version of Terraform for remote operations, we +remote workspaces are empty or absent, Terraform will create workspaces and +update the remote state accordingly. However, if your workspace requires variables or 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. +### Workspace Names + +Terraform uses shortened names without the common prefix to interact with workspaces on the command line. For example, if `prefix = "networking-"`, use `terraform workspace select prod` to switch to the Terraform CLI workspace `prod` within the current configuration. However, remote Terraform operations such as `plan` and `apply` for that Terraform CLI workspace will take place in the Terraform Cloud workspace `networking-prod`. + +Because of this, the [`terraform.workspace`](/language/state/workspaces#current-workspace-interpolation) interpolation expression produces different results depending on whether a remote workspace is configured to perform operations locally or remotely. For example, in a remote workspace called `networking-prod` created with `prefix = "networking-"` the expression produces the following: + +- For local operations, `terraform.workspace` = `prod` +- For remote operations, `terraform.workspace`= `networking-prod` + +Prior to Terraform version 1.1.0, Terraform Cloud workspaces used only the single `default` Terraform CLI workspace internally. So if a 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 set with the `terraform workspace select` command. Therefore, we do not recommend using `terraform.workspace` in Terraform configurations that use Terraform 1.0.x or earlier and run remote operations against Terraform Cloud workspaces. + +### Determining Run Environment + +To determine whether a run is local or remote, we recommend using [Terraform Cloud run environment variables](/cloud-docs/run/run-environment#environment-variables). The example below uses `TFC_RUN_ID`. + +``` +output "current_workspace_name" { + value = terraform.workspace +} + +variable "TFC_RUN_ID" { + type = string + default = "" +} + +output "remote_execution_determine" { + value = "Remote run environment? %{if var.TFC_RUN_ID != ""}Yes%{else}No this is local%{endif}!" +} +``` + + ## Example Configurations -> **Note:** We recommend omitting the token from the configuration, and instead using From faffa11e08d0be227682d7dc3fd09472abce613a Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Wed, 9 Feb 2022 14:21:46 -0500 Subject: [PATCH 2/5] Update workspaces page --- website/docs/language/state/workspaces.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/website/docs/language/state/workspaces.mdx b/website/docs/language/state/workspaces.mdx index a3f38d447..ffd202074 100644 --- a/website/docs/language/state/workspaces.mdx +++ b/website/docs/language/state/workspaces.mdx @@ -201,8 +201,6 @@ 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 only locally in the ignored +The "current workspace" name is stored locally in the ignored `.terraform` directory. This allows multiple team members to work on -different workspaces concurrently. The "current workspace" name is **not** -currently meaningful in Terraform Cloud workspaces since it will always -have the value `default`. +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](/cli/cloud/settings#arguments) (recommended) documentation. From 8be2c4a3972f706c52c4b8df88e37cd2fd0ca6a2 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Wed, 9 Feb 2022 14:30:02 -0500 Subject: [PATCH 3/5] fix link --- 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 ffd202074..cca441944 100644 --- a/website/docs/language/state/workspaces.mdx +++ b/website/docs/language/state/workspaces.mdx @@ -203,4 +203,4 @@ meant to be a shared resource. They aren't a private, local-only notion 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](/cli/cloud/settings#arguments) (recommended) documentation. +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 422b47618c7919fbca1a1197d4e51760e1334903 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Wed, 9 Feb 2022 17:37:06 -0500 Subject: [PATCH 4/5] Change name example to match new edits --- website/docs/language/settings/backends/remote.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/language/settings/backends/remote.mdx b/website/docs/language/settings/backends/remote.mdx index d15fd2162..30227e1a0 100644 --- a/website/docs/language/settings/backends/remote.mdx +++ b/website/docs/language/settings/backends/remote.mdx @@ -45,7 +45,7 @@ The remote backend can work with either a single remote Terraform Cloud workspac determines which mode it uses: - To use a single remote Terraform Cloud workspace, set `workspaces.name` to the - remote workspace's full name (like `networking`). + remote workspace's full name (like `networking-prod`). - To use multiple remote workspaces, set `workspaces.prefix` to a prefix used in all of the desired remote workspace names. For example, set From 24cffb5ff3046530537473c0b2336e8ed5cbc430 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Wed, 9 Feb 2022 17:41:12 -0500 Subject: [PATCH 5/5] Soften language for determining run environment --- website/docs/language/settings/backends/remote.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/language/settings/backends/remote.mdx b/website/docs/language/settings/backends/remote.mdx index 30227e1a0..f4b09be33 100644 --- a/website/docs/language/settings/backends/remote.mdx +++ b/website/docs/language/settings/backends/remote.mdx @@ -79,7 +79,7 @@ which workspace you set with the `terraform workspace select` command. Therefore ### Determining Run Environment -To determine whether a run is local or remote, we recommend using [Terraform Cloud run environment variables](/cloud-docs/run/run-environment#environment-variables). The example below uses `TFC_RUN_ID`. +If you need to determine whether a run is local or remote in your Terraform configuration, we recommend using [Terraform Cloud run environment variables](/cloud-docs/run/run-environment#environment-variables). The example below uses `TFC_RUN_ID`. ``` output "current_workspace_name" {