Add Terraform Cloud integration docs

This commit is contained in:
Chris Arcand 2021-12-07 15:29:11 -06:00
parent b80e98ab47
commit 099c7269e4
9 changed files with 277 additions and 12 deletions

View File

@ -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.

View File

@ -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.

View File

@ -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
`<COMPONENT>-<ENVIRONMENT>-<REGION>` (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"]
}
}
}
```

View File

@ -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.

View File

@ -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 workspace has its own Terraform configuration, set of variable values, state
data, run history, and settings. data, run history, and settings.
These two kinds of workspaces are different, but related. When using Terraform These two kinds of workspaces are different, but related. When [using Terraform
CLI as a frontend for Terraform Cloud, you associate the current working 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 by configuring directory with one or more remote workspaces. If you associate the
[the `remote` backend](/docs/language/settings/backends/remote.html). If you associate the directory with multiple workspaces (using workspace tags), you can use the
directory with multiple workspaces (using a name prefix), you can use the
`terraform workspace` commands to select which remote workspace to use. `terraform workspace` commands to select which remote workspace to use.
For more information about using Terraform CLI with Terraform Cloud, see For more information about using Terraform CLI with Terraform Cloud, see

View File

@ -38,7 +38,7 @@ The nested `cloud` block configures Terraform Cloud for enabling its
[Terraform Cloud Configuration](/docs/language/settings/terraform-cloud.html). [Terraform Cloud Configuration](/docs/language/settings/terraform-cloud.html).
- For more complete details about configuring and using Terraform Cloud with Terraform CLI, - 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. Terraform CLI documentation.
## Configuring a Terraform Backend ## Configuring a Terraform Backend

View File

@ -33,5 +33,5 @@ can only declare one or the other. Similar to backends...
- A configuration can only provide one cloud block. - A configuration can only provide one cloud block.
- A cloud block cannot refer to named values (like input variables, locals, or data source attributes). - 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. in the Terraform CLI docs for more information.

View File

@ -80,10 +80,7 @@ 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. However, it should **not** be be used anywhere interpolations are allowed.
used in remote operations against Terraform Cloud workspaces. For an
explanation, see the [remote backend](/docs/language/settings/backends/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

View File

@ -334,6 +334,27 @@
</ul> </ul>
</li> </li>
<li>
<a href="#">Using Terraform Cloud</a>
<ul class="nav">
<li>
<a href="/docs/cli/cloud/index.html">Overview</a>
</li>
<li>
<a href="/docs/cli/cloud/settings.html">Terraform Cloud Settings</a>
</li>
<li>
<a href="/docs/cli/cloud/migrating.html">Initializing and Migrating</a>
</li>
<li>
<a href="/docs/cli/cloud/command-line-arguments.html">Command Line Arguments</a>
</li>
</ul>
</li>
<li> <li>
<a href="#">Automating Terraform</a> <a href="#">Automating Terraform</a>
<ul class="nav"> <ul class="nav">