From 099c7269e453ad290033133b90e8ff9ccc2a6b17 Mon Sep 17 00:00:00 2001 From: Chris Arcand Date: Tue, 7 Dec 2021 15:29:11 -0600 Subject: [PATCH] Add Terraform Cloud integration docs --- .../cli/cloud/command-line-arguments.html.md | 27 +++++ website/docs/cli/cloud/index.html.md | 32 ++++++ website/docs/cli/cloud/migrating.html.md | 86 +++++++++++++++ website/docs/cli/cloud/settings.html.md | 103 ++++++++++++++++++ website/docs/cli/workspaces/index.html.md | 9 +- website/docs/language/settings/index.html.md | 2 +- .../language/settings/terraform-cloud.html.md | 2 +- .../docs/language/state/workspaces.html.md | 5 +- website/layouts/docs.erb | 23 +++- 9 files changed, 277 insertions(+), 12 deletions(-) create mode 100644 website/docs/cli/cloud/command-line-arguments.html.md create mode 100644 website/docs/cli/cloud/index.html.md create mode 100644 website/docs/cli/cloud/migrating.html.md create mode 100644 website/docs/cli/cloud/settings.html.md diff --git a/website/docs/cli/cloud/command-line-arguments.html.md b/website/docs/cli/cloud/command-line-arguments.html.md new file mode 100644 index 000000000..ca51ce0e7 --- /dev/null +++ b/website/docs/cli/cloud/command-line-arguments.html.md @@ -0,0 +1,27 @@ +--- +layout: "docs" +page_title: "Command Line Arguments" +description: "Command Line Arguments" +--- + +# Command Line Arguments + +When your configuration includes a `cloud` block, commands that +make local modifications to Terraform state and then push them back up to the remote workspace +accept the following option to modify that behavior: + +* `-ignore-remote-version` - Override checking that the local and remote + Terraform versions agree, making an operation proceed even when there is + a mismatch. + + Normally state-modification operations require using a local version of + Terraform CLI that is compatible with the Terraform version selected + for the remote workspace as part of its settings. This is to avoid the + local operation creating a new state snapshot that the workspace's + remote execution environment would then be unable to decode. + + Overriding this check can result in a Terraform Cloud workspace that is no + longer able to complete remote operations with the currently selected + version of Terraform, so we recommend against using this option unless + absolutely necessary. + diff --git a/website/docs/cli/cloud/index.html.md b/website/docs/cli/cloud/index.html.md new file mode 100644 index 000000000..e6a0c6acb --- /dev/null +++ b/website/docs/cli/cloud/index.html.md @@ -0,0 +1,32 @@ +--- +layout: "docs" +page_title: "Using Terraform Cloud - Terraform CLI" +--- + +# Using Terraform Cloud with Terraform + +The Terraform Cloud CLI Integration allows you to use Terraform Cloud and Terraform Enterprise on the command line. In the documentation Terraform Cloud instructions also apply to Terraform Enterprise, except where explicitly stated. + +Using Terraform Cloud through the command line is called the [CLI-driven run workflow](/docs/cloud/run/cli.html). When you use the CLI workflow, operations like `terraform plan` or `terraform apply` are remotely executed in Terraform Cloud's run environment by default, with log output streaming to the local terminal. This lets you use Terraform Cloud features within the familiar Terraform CLI workflow, including variables encrypted at rest in a Terraform Cloud workspace, cost estimates, and policy checking. + +Workspaces can also be configured for local execution, in which case only state is stored in +Terraform Cloud. In this mode, Terraform Cloud behaves just like a standard state backend. + +-> **Note:** The Cloud integration for Terraform was added in Terraform 1.1.0; for previous +versions, see the [remote backend documentation](/docs/language/settings/backends/remote.html). See +also: [Migrating from the remote +backend](/docs/cli/cloud/migrating.html) + +-> **Note:** This integration supports Terraform Enterprise as well. Throughout all the +documentation, the platform will be referred to as Terraform Cloud, with any Terraform +Enterprise-specific details explicitly stated. The minimum required version of Terraform Enterprise +is 202201-1. + +## Documentation Summary + +- [Terraform Cloud Settings](/docs/cli/cloud/settings.html) documents the `cloud` block that you must add to your configuration to enable Terraform Cloud support. +- [Initializing and Migrating](/docs/cli/cloud/migrating.html) describes +how to start using Terraform Cloud with a working directory that already has state data. +- [Command Line Arguments](/docs/cli/cloud/command-line-arguments.html) lists the Terraform command flags that are specific to using Terraform with Terraform Cloud. + +Refer to the [CLI-driven Run Workflow](/docs/cloud/run/cli.html) for more details about how to use Terraform Cloud from the command line. diff --git a/website/docs/cli/cloud/migrating.html.md b/website/docs/cli/cloud/migrating.html.md new file mode 100644 index 000000000..ca24b3106 --- /dev/null +++ b/website/docs/cli/cloud/migrating.html.md @@ -0,0 +1,86 @@ +--- +layout: "docs" +page_title: "Initializing and Migrating to Terraform Cloud - Terraform CLI" +--- + +# Initializing and Migrating + +After [configuring Terraform Cloud settings](/docs/cli/cloud/settings.html) for a working directory, you must run `terraform init` to finish setting up. When running this command, Terraform may guide you through an interactive process where you may choose whether or not you'd like to migrate state from any existing workspaces. + +There are three potential scenarios: + +1. **Fresh working directory:** If the working directory has no existing Terraform state, no migrations will occur. You can start using Terraform with Terraform Cloud right away, creating workspaces and starting runs. +2. **State backend or local state:** If the working directory already has state data in one or more workspaces (using either local state or a [state backend](/docs/language/settings/backends/index.html)), Terraform will ask if you're like to migrate that state to new Terraform Cloud workspaces. You will need permission to manage workspaces in the destination Terraform Cloud organization. You may also be prompted to rename the workspaces being migrated, to better distinguish them within a Terraform Cloud organization. +3. **`remote` backend:** If the working directory was already connected to Terraform Cloud with the `remote` backend, Terraform can continue using the same Terraform Cloud workspaces. The local names shown for those workspaces will change to match their remote names. + +The rest of this page briefly describes cases 2 and 3. + +## Migrating from Local State or Other Backends + +If the working directory already has state data available (using either local state or a [state +backend](/docs/language/settings/backends/index.html)), Terraform will ask your approval to migrate +that state to Terraform Cloud. This process is interactive and self-documenting, and resembles +moving between state backends. + +You may also be prompted to rename your workspaces during the migration, to either give a name to +the unnamed `default` workspace (Terraform Cloud requires all workspaces to have a name) or give +your workspace names more contextual information. Unlike typical Terraform workspaces representing +an environment associated with a particular configuration (e.g. production, staging, development), +Terraform Cloud workspaces are named uniquely across all configurations used within an organization. +Because of this, you'll be given an opportunity to rename the working directory's workspaces +according to a pattern relative to their existing names. A typical strategy to start with is +`--` (e.g. `networking-prod-us-east`, +`networking-staging-us-east`). For more information on workspace naming, see [Workspace +Naming](/docs/cloud/workspaces/naming.html) in the Terraform Cloud documentation. + +## Migrating from the `remote` Backend + +The [`remote` backend](/docs/language/settings/backends/remote.html) was the primary +implementation of Terraform Cloud's [CLI-driven run workflow](/docs/cloud/run/cli.html) for +Terraform versions 0.11.13 through 1.0.x. We recommend using the native `cloud` +integration for Terraform versions 1.1 or later, as it provides an improved user experience and +various enhancements. + +### Block Replacement + +When switching from the `remote` backend to a `cloud` block, Terraform will continue using the same +set of Terraform Cloud workspaces. Replace your `backend "remote"` block with an equivalent `cloud` +block: + +- If you were using a single workspace via the `name` argument, change the block + label to `cloud`. + + ```diff + terraform { + - backend "remote" { + + cloud { + organization = "my-org" + + workspaces { + name = "my-app-prod" + } + } + } + ``` + +- If you were using multiple workspaces via the `prefix` argument, replace it + with a `cloud` block that uses the `tags` argument. You may specify any number of tags to + distinguish the workspaces for your working directory, but a good starting point may be to use + whatever the prefix was before. + + The existing workspaces don't need to already have these tags — when you + initialize, Terraform will add the specified tags to them. + + ```diff + terraform { + - backend "remote" { + + cloud { + organization = "my-org" + + workspaces { + - prefix = "my-app-" + + tags = ["app:mine"] + } + } + } + ``` diff --git a/website/docs/cli/cloud/settings.html.md b/website/docs/cli/cloud/settings.html.md new file mode 100644 index 000000000..7ad3b290d --- /dev/null +++ b/website/docs/cli/cloud/settings.html.md @@ -0,0 +1,103 @@ +--- +layout: "docs" +page_title: "Terraform Cloud Settings - Terraform CLI" +--- + +# Terraform Cloud Settings + +Terraform CLI can integrate with Terraform Cloud, acting as a client for Terraform Cloud's +[CLI-driven run workflow](https://www.terraform.io/docs/cloud/run/cli.html). + +To use Terraform Cloud for a particular working directory, you must configure the following settings: + +- Provide credentials to access Terraform Cloud, preferably by using the + [`terraform login`](/docs/cli/commands/login.html) command. +- Add a `cloud` block to the directory's Terraform configuration, to specify + which organization and workspace(s) to use. +- Optionally, use a `.terraformignore` file to specify files that shouldn't be + uploaded with the Terraform configuration when running plans and applies. + +After adding or changing a `cloud` block, you must run `terraform init`. + +## The `cloud` Block + +The `cloud` block is a nested block within the top-level `terraform` settings +block. It specifies which Terraform Cloud workspaces to use for the current +working directory. + +```hcl +terraform { + cloud { + organization = "my-org" + hostname = "app.terraform.io" # Optional; defaults to app.terraform.io + + workspaces { + tags = ["networking", "source:cli"] + } + } +} +``` + +The `cloud` block has some special restrictions: + +- A configuration can only provide one `cloud` block. +- A `cloud` block cannot be used with [state backends](/docs/language/settings/backends/index.html). + A configuration can use one or the other, but not both. +- A cloud block cannot refer to named values (like input variables, locals, or + data source attributes). + +The `cloud` block only affects Terraform CLI's behavior. When Terraform Cloud uses a configuration +that contains a cloud block - for example, when a workspace is configured to use a VCS provider +directly - it ignores the block and behaves according to its own workspace settings. + +### Arguments + +The `cloud` block supports the following configuration arguments: + +* `organization` - (Required) The name of the organization containing the + workspace(s) the current configuration should use. + +* `workspaces` - (Required) A nested block that specifies which remote Terraform Cloud workspaces to +use for the current configuration. The `workspaces` block must contain **exactly one** of the +following arguments, each denoting a strategy for how workspaces should be mapped: + + * `tags` - (Optional) A set of Terraform Cloud workspace tags. You will be able to use + this working directory with any workspaces that have all of the specified tags, + and can use [the `terraform workspace` commands](/docs/cli/workspaces/index.html) + to switch between them or create new workspaces; new workspaces will automatically have + the specified tags. This option conflicts with `name`. + + * `name` - (Optional) The name of a single Terraform Cloud workspace. You will + only be able to use the workspace specified in the configuration with this working + directory, and cannot manage workspaces from the CLI (e.g. `terraform workspace select` or + `terraform workspace new`). This option conflicts with `tags`. + +* `hostname` - (Optional) The hostname of a Terraform Enterprise installation, if using Terraform + Enterprise. Defaults to Terraform Cloud (app.terraform.io). + +* `token` - (Optional) The token used to authenticate with Terraform Cloud. + We recommend omitting the token from the configuration, and instead using + [`terraform login`](/docs/cli/commands/login.html) or manually configuring + `credentials` in the + [CLI config file](/docs/cli/config/config-file.html#credentials). + +## Excluding Files from Upload with .terraformignore + +When executing a remote `plan` or `apply` in a [CLI-driven run](/docs/cloud/run/cli.html), +a copy of your configuration directory is uploaded to Terraform Cloud. You can define +paths to exclude from upload by adding a `.terraformignore` file at the root of your +configuration directory. If this file is not present, the upload will exclude +the following by default: + +* `.git/` directories +* `.terraform/` directories (exclusive of `.terraform/modules`) + +The rules in `.terraformignore` file resemble the rules allowed in a +[.gitignore file](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring): + +* Comments (starting with `#`) or blank lines are ignored. +* End a pattern with a forward slash `/` to specify a directory. +* Negate a pattern by starting it with an exclamation point `!`. + +Note that unlike `.gitignore`, only the `.terraformignore` at the root of the configuration +directory is considered. diff --git a/website/docs/cli/workspaces/index.html.md b/website/docs/cli/workspaces/index.html.md index e8a5dcb5e..6143c3087 100644 --- a/website/docs/cli/workspaces/index.html.md +++ b/website/docs/cli/workspaces/index.html.md @@ -68,11 +68,10 @@ 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 associate the current working -directory with one or more remote workspaces by configuring -[the `remote` backend](/docs/language/settings/backends/remote.html). If you associate the -directory with multiple workspaces (using a name prefix), you can use the +These two kinds of workspaces are different, but related. When [using Terraform +CLI as a frontend for Terraform Cloud](/docs/cli/cloud/index.html), 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. For more information about using Terraform CLI with Terraform Cloud, see diff --git a/website/docs/language/settings/index.html.md b/website/docs/language/settings/index.html.md index fbeec6c4c..9c17d2f58 100644 --- a/website/docs/language/settings/index.html.md +++ b/website/docs/language/settings/index.html.md @@ -38,7 +38,7 @@ The nested `cloud` block configures Terraform Cloud for enabling its [Terraform Cloud Configuration](/docs/language/settings/terraform-cloud.html). - For more complete details about configuring and using Terraform Cloud with Terraform CLI, -see [Configuring Terraform Cloud](/docs/cli/cloud/index.html) in the +see [Using Terraform Cloud](/docs/cli/cloud/index.html) in the Terraform CLI documentation. ## Configuring a Terraform Backend diff --git a/website/docs/language/settings/terraform-cloud.html.md b/website/docs/language/settings/terraform-cloud.html.md index e0887c2a0..854863ad4 100644 --- a/website/docs/language/settings/terraform-cloud.html.md +++ b/website/docs/language/settings/terraform-cloud.html.md @@ -33,5 +33,5 @@ can only declare one or the other. Similar to backends... - A configuration can only provide one cloud block. - A cloud block cannot refer to named values (like input variables, locals, or data source attributes). -See [Configuring Terraform Cloud](/docs/cli/cloud/index.html) +See [Using Terraform Cloud](/docs/cli/cloud/index.html) in the Terraform CLI docs for more information. diff --git a/website/docs/language/state/workspaces.html.md b/website/docs/language/state/workspaces.html.md index a675d8edd..c33cad7d3 100644 --- a/website/docs/language/state/workspaces.html.md +++ b/website/docs/language/state/workspaces.html.md @@ -80,10 +80,7 @@ Terraform workspace. Within your Terraform configuration, you may include the name of the current workspace using the `${terraform.workspace}` interpolation sequence. This can -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](/docs/language/settings/backends/remote.html#workspaces) -document. +be used anywhere interpolations are allowed. Referencing the current workspace is useful for changing behavior based on the workspace. For example, for non-default workspaces, it may be useful diff --git a/website/layouts/docs.erb b/website/layouts/docs.erb index 602a490e5..059d25d7f 100644 --- a/website/layouts/docs.erb +++ b/website/layouts/docs.erb @@ -334,6 +334,27 @@ +
  • + Using Terraform Cloud + +
    • +
  • Automating Terraform