Skip to content

Commit 81136ce

Browse files
chrisarcandchrisarcand
authored
Merge pull request hashicorp#30102 from hashicorp/tfc-integration-docs-again
Add Terraform Cloud integration docs
2 parents 5090462 + 70740e9 commit 81136ce

31 files changed

Lines changed: 411 additions & 177 deletions

‎docs/architecture.md‎

Lines changed: 11 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -61,29 +61,22 @@ Backends that are able to execute operations additionally implement
6161
the command-handling code calls `Operation` with the operation it has
6262
constructed, and then the backend is responsible for executing that action.
6363

64-
Most backends do _not_ implement this interface, and so the `command` package
65-
wraps these backends in an instance of
64+
Backends that execute operations, however, do so as an architectural implementation detail and not a
65+
general feature of backends. That is, the term 'backend' as a Terraform feature is used to refer to
66+
a plugin that determines where Terraform stores its state snapshots - only the default `local`
67+
backend and Terraform Cloud's backends (`remote`, `cloud`) perform operations.
68+
69+
Thus, most backends do _not_ implement this interface, and so the `command` package wraps these
70+
backends in an instance of
6671
[`local.Local`](https://pkg.go.dev/github.com/hashicorp/terraform/internal/backend/local#Local),
67-
causing the operation to be executed locally within the `terraform` process
68-
itself, which (at the time of writing) is currently the only way an operation
69-
can be executed.
72+
causing the operation to be executed locally within the `terraform` process itself.
7073

7174
## Backends
7275

73-
A _backend_ has a number of responsibilities in Terraform:
74-
75-
* Execute operations (e.g. plan, apply)
76-
* Store state
77-
* Store workspace-defined variables (in the future; not yet implemented)
78-
79-
As described above, the `local.Local` implementation -- named `local` from the
80-
user's standpoint -- is the only backend which implements _all_ functionality.
81-
Backends that cannot execute operations (at the time of writing, all except
82-
`local`) can be wrapped inside `local.Local` to perform operations locally
83-
while storing the [state](https://www.terraform.io/docs/state/index.html)
84-
elsewhere.
76+
A _backend_ determines where Terraform should store its state snapshots.
8577

86-
To execute an operation locally, the `local` backend uses a _state manager_
78+
As described above, the `local` backend also executes operations on behalf of most other
79+
backends. It uses a _state manager_
8780
(either
8881
[`statemgr.Filesystem`](https://pkg.go.dev/github.com/hashicorp/terraform/internal/states/statemgr#Filesystem) if the
8982
local backend is being used directly, or an implementation provided by whatever

‎internal/backend/backend.go‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -118,9 +118,10 @@ type Backend interface {
118118

119119
// Enhanced implements additional behavior on top of a normal backend.
120120
//
121-
// Enhanced backends allow customizing the behavior of Terraform operations.
122-
// This allows Terraform to potentially run operations remotely, load
123-
// configurations from external sources, etc.
121+
// 'Enhanced' backends are an implementation detail only, and are no longer reflected as an external
122+
// 'feature' of backends. In other words, backends refer to plugins for remote state snapshot
123+
// storage only, and the Enhanced interface here is a necessary vestige of the 'local' and
124+
// remote/cloud backends only.
124125
type Enhanced interface {
125126
Backend
126127

‎website/docs/cli/cloud/command-line-arguments.html.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
layout: "docs"
3+
page_title: "Command Line Arguments"
4+
description: "Command Line Arguments"
5+
---
6+
7+
# Command Line Arguments
8+
9+
When your configuration includes a `cloud` block, commands that
10+
make local modifications to Terraform state and then push them back up to the remote workspace
11+
accept the following option to modify that behavior:
12+
13+
- `-ignore-remote-version` - Override checking that the local and remote
14+
Terraform versions agree, making an operation proceed even when there is
15+
a mismatch.
16+
17+
State-modification operations usually require using a local version of the
18+
Terraform CLI that is compatible with the Terraform version selected
19+
in the remote workspace settings. This prevents the
20+
local operation from creating a new state snapshot that the workspace's
21+
remote execution environment cannot decode.
22+
23+
We recommend against using this option unless absolutely necessary. Overriding this check can result
24+
in a Terraform Cloud workspace that is no longer able to complete remote operations with the currently
25+
selected version of Terraform.
26+

‎website/docs/cli/cloud/index.html.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
layout: "docs"
3+
page_title: "Using Terraform Cloud - Terraform CLI"
4+
---
5+
6+
# Using Terraform Cloud with Terraform CLI
7+
8+
The Terraform CLI's integration with Terraform Cloud lets 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.
9+
10+
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.
11+
12+
> **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn.
13+
14+
Workspaces can also be configured for local execution, in which case only state is stored in
15+
Terraform Cloud. In this mode, Terraform Cloud behaves just like a standard state backend.
16+
17+
-> **Note:** The CLI integration is available in Terraform 1.1.0 and later, and Terraform Enterprise 202201-1 and later. Previous versions can use the [`remote` backend](/docs/language/settings/backends/remote.html). Refer to [Migrating from the remote
18+
backend](/docs/cli/cloud/migrating.html) for details about switching to the CLI integration.
19+
20+
21+
## Documentation Summary
22+
23+
- [Terraform Cloud Settings](/docs/cli/cloud/settings.html) documents the `cloud` block that you must add to your configuration to enable Terraform Cloud support.
24+
- [Initializing and Migrating](/docs/cli/cloud/migrating.html) describes
25+
how to start using Terraform Cloud with a working directory that already has state data.
26+
- [Command Line Arguments](/docs/cli/cloud/command-line-arguments.html) lists the Terraform command flags that are specific to using Terraform with Terraform Cloud.
27+
28+
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.

‎website/docs/cli/cloud/migrating.html.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
layout: "docs"
3+
page_title: "Initializing and Migrating to Terraform Cloud - Terraform CLI"
4+
---
5+
6+
# Initializing and Migrating
7+
8+
After [configuring Terraform Cloud settings](/docs/cli/cloud/settings.html) for a working directory, you must run `terraform init` to finish setting up. If the working directory has no existing Terraform state, you can start using Terraform with Terraform Cloud right away. Refer to [CLI-driven run workflow](/docs/cloud/run/cli.html) for more details.
9+
10+
When you run `terraform init` in the following scenarios, Terraform will ask you to choose whether or not to migrate state from any existing workspaces.
11+
12+
1. [**Migrating from local state or state backends:**](#migrating-from-local-state-or-state-backends) If the working directory already has state data in one or more workspaces, Terraform will ask if you would like to migrate that state to new Terraform Cloud workspaces.
13+
14+
2. [**Migrating from the `remote` backend:**](#migrating-from-the-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. You will need to switch the `remote` backend block to the `cloud` block.
15+
16+
## Migrating from Local State or State Backends
17+
18+
> **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn.
19+
20+
If the working directory already has state data available (using either local state or a [state
21+
backend](/docs/language/settings/backends/index.html)), Terraform will ask your approval to migrate
22+
that state to Terraform Cloud. You will need permission to manage workspaces in the destination Terraform Cloud organization. This process is interactive and self-documenting, and resembles
23+
moving between state backends.
24+
25+
Terraform may also prompt you to rename your workspaces during the migration, to either give a name to
26+
the unnamed `default` workspace (Terraform Cloud requires all workspaces to have a name) or give
27+
your workspace names more contextual information. Unlike Terraform CLI-only workspaces, which represent
28+
multiple environments associated with the same configuration (e.g. production, staging, development),
29+
Terraform Cloud workspaces can represent totally independent configurations, and must have unique names within the Terraform Cloud organization.
30+
31+
Because of this, Terraform will prompt you to rename the working directory's workspaces
32+
according to a pattern relative to their existing names. This can indicate the fact that these specific workspaces share configuration. A typical strategy is
33+
`<COMPONENT>-<ENVIRONMENT>-<REGION>` (e.g., `networking-prod-us-east`,
34+
`networking-staging-us-east`). Refer to [Workspace
35+
Naming](/docs/cloud/workspaces/naming.html) in the Terraform Cloud documentation for more detail.
36+
37+
## Migrating from the `remote` Backend
38+
39+
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.
40+
41+
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.
42+
43+
### Block Replacement
44+
45+
When switching from the `remote` backend to a `cloud` block, Terraform will continue using the same
46+
set of Terraform Cloud workspaces. Replace your `backend "remote"` block with an equivalent `cloud`
47+
block.
48+
49+
#### Single Workspace
50+
51+
If you were using a single workspace with the `name` argument, change the block
52+
label to `cloud`.
53+
54+
```diff
55+
terraform {
56+
- backend "remote" {
57+
+ cloud {
58+
organization = "my-org"
59+
60+
workspaces {
61+
name = "my-app-prod"
62+
}
63+
}
64+
}
65+
```
66+
67+
#### Multiple Workspaces
68+
69+
If you were using multiple workspaces with 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.
70+
71+
The tags you configure do not need to be present on the existing workspaces. When you initialize, Terraform will add the specified tags to the workspaces if necessary.
72+
73+
```diff
74+
terraform {
75+
- backend "remote" {
76+
+ cloud {
77+
organization = "my-org"
78+
79+
workspaces {
80+
- prefix = "my-app-"
81+
+ tags = ["app:mine"]
82+
}
83+
}
84+
}
85+
```

‎website/docs/cli/cloud/settings.html.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
layout: "docs"
3+
page_title: "Terraform Cloud Settings - Terraform CLI"
4+
---
5+
6+
# Terraform Cloud Settings
7+
8+
Terraform CLI can integrate with Terraform Cloud, acting as a client for Terraform Cloud's
9+
[CLI-driven run workflow](https://www.terraform.io/docs/cloud/run/cli.html).
10+
11+
> **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn.
12+
13+
You must configure the following settings to use Terraform Cloud for a particular working directory:
14+
15+
- Provide credentials to access Terraform Cloud, preferably by using the
16+
[`terraform login`](/docs/cli/commands/login.html) command.
17+
- Add a `cloud` block to the directory's Terraform configuration, to specify
18+
which organization and workspace(s) to use.
19+
- Optionally, use a `.terraformignore` file to specify files that shouldn't be
20+
uploaded with the Terraform configuration when running plans and applies.
21+
22+
After adding or changing a `cloud` block, you must run `terraform init`.
23+
24+
## The `cloud` Block
25+
26+
The `cloud` block is a nested block within the top-level `terraform` settings
27+
block. It specifies which Terraform Cloud workspaces to use for the current
28+
working directory.
29+
30+
```hcl
31+
terraform {
32+
cloud {
33+
organization = "my-org"
34+
hostname = "app.terraform.io" # Optional; defaults to app.terraform.io
35+
36+
workspaces {
37+
tags = ["networking", "source:cli"]
38+
}
39+
}
40+
}
41+
```
42+
43+
The `cloud` block also has some special restrictions:
44+
45+
- A configuration can only provide one `cloud` block.
46+
- A `cloud` block cannot be used with [state backends](/docs/language/settings/backends/index.html).
47+
A configuration can use one or the other, but not both.
48+
- A `cloud` block cannot refer to named values (like input variables, locals, or
49+
data source attributes).
50+
51+
The `cloud` block only affects Terraform CLI's behavior. When Terraform Cloud uses a configuration
52+
that contains a cloud block - for example, when a workspace is configured to use a VCS provider
53+
directly - it ignores the block and behaves according to its own workspace settings.
54+
55+
### Arguments
56+
57+
The `cloud` block supports the following configuration arguments:
58+
59+
- `organization` - (Required) The name of the organization containing the
60+
workspace(s) the current configuration should use.
61+
62+
- `workspaces` - (Required) A nested block that specifies which remote Terraform Cloud workspaces to
63+
use for the current configuration. The `workspaces` block must contain **exactly one** of the
64+
following arguments, each denoting a strategy for how workspaces should be mapped:
65+
66+
- `tags` - (Optional) A set of Terraform Cloud workspace tags. You will be able to use
67+
this working directory with any workspaces that have all of the specified tags,
68+
and can use [the `terraform workspace` commands](/docs/cli/workspaces/index.html)
69+
to switch between them or create new workspaces. New workspaces will automatically have
70+
the specified tags. This option conflicts with `name`.
71+
72+
- `name` - (Optional) The name of a single Terraform Cloud workspace. You will
73+
only be able to use the workspace specified in the configuration with this working
74+
directory, and cannot manage workspaces from the CLI (e.g. `terraform workspace select` or
75+
`terraform workspace new`). This option conflicts with `tags`.
76+
77+
- `hostname` - (Optional) The hostname of a Terraform Enterprise installation, if using Terraform
78+
Enterprise. Defaults to Terraform Cloud (app.terraform.io).
79+
80+
- `token` - (Optional) The token used to authenticate with Terraform Cloud.
81+
We recommend omitting the token from the configuration, and instead using
82+
[`terraform login`](/docs/cli/commands/login.html) or manually configuring
83+
`credentials` in the
84+
[CLI config file](/docs/cli/config/config-file.html#credentials).
85+
86+
## Excluding Files from Upload with .terraformignore
87+
88+
When executing a remote `plan` or `apply` in a [CLI-driven run](/docs/cloud/run/cli.html),
89+
a copy of your configuration directory is uploaded to Terraform Cloud. You can define
90+
paths to exclude from upload by adding a `.terraformignore` file at the root of your
91+
configuration directory. If this file is not present, the upload will exclude
92+
the following by default:
93+
94+
- `.git/` directories
95+
- `.terraform/` directories (exclusive of `.terraform/modules`)
96+
97+
The rules in `.terraformignore` file resemble the rules allowed in a
98+
[.gitignore file](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring):
99+
100+
- Comments (starting with `#`) or blank lines are ignored.
101+
- End a pattern with a forward slash `/` to specify a directory.
102+
- Negate a pattern by starting it with an exclamation point `!`.
103+
104+
-> **Note:** Unlike `.gitignore`, only the `.terraformignore` at the root of the configuration directory is considered.

‎website/docs/cli/state/move.html.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ resource.
2525
real-world object. Use this to preserve an object when renaming a resource, or
2626
when moving a resource into or out of a child module.
2727

28+
> **Hands On:** Try the [Use Configuration to Move Resources](https://learn.hashicorp.com/tutorials/terraform/move-config) on HashiCorp Learn.
29+
2830
- [The `terraform state rm` command](/docs/cli/commands/state/rm.html) tells
2931
Terraform to stop managing a resource as part of the current working directory
3032
and workspace, _without_ destroying the corresponding real-world object. (You

‎website/docs/cli/workspaces/index.html.md‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -68,12 +68,10 @@ act more like completely separate working directories; each Terraform Cloud
6868
workspace has its own Terraform configuration, set of variable values, state
6969
data, run history, and settings.
7070

71-
These two kinds of workspaces are different, but related. When using Terraform
72-
CLI as a frontend for Terraform Cloud, you associate the current working
73-
directory with one or more remote workspaces by configuring
74-
[the `remote` backend](/docs/language/settings/backends/remote.html). If you associate the
75-
directory with multiple workspaces (using a name prefix), you can use the
71+
These two kinds of workspaces are different, but related. When [using Terraform
72+
CLI as a frontend for Terraform Cloud](/docs/cli/cloud/index.html), you can associate the current working
73+
directory with one or more remote workspaces. If you associate the
74+
directory with multiple workspaces (using workspace tags), you can use the
7675
`terraform workspace` commands to select which remote workspace to use.
7776

78-
For more information about using Terraform CLI with Terraform Cloud, see
79-
[CLI-driven Runs](/docs/cloud/run/cli.html) in the Terraform Cloud docs.
77+
Refer to [CLI-driven Runs](/docs/cloud/run/cli.html) in the Terraform Cloud documentation for more details about using Terraform CLI with Terraform Cloud.

‎website/docs/language/settings/backends/artifactory.html.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,6 @@ description: |-
88

99
# artifactory
1010

11-
**Kind: Standard (with no locking)**
12-
1311
Stores the state as an artifact in a given repository in
1412
[Artifactory](https://www.jfrog.com/artifactory/).
1513

@@ -19,6 +17,8 @@ configurations may be kept at different subpaths within the repository.
1917
-> **Note:** The URL must include the path to the Artifactory installation.
2018
It will likely end in `/artifactory`.
2119

20+
This backend does **not** support [state locking](/docs/language/state/locking.html).
21+
2222
## Example Configuration
2323

2424
```hcl

‎website/docs/language/settings/backends/azurerm.html.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,9 @@ description: |-
99

1010
# azurerm
1111

12-
**Kind: Standard (with state locking)**
12+
Stores the state as a Blob with the given Key within the Blob Container within [the Blob Storage Account](https://docs.microsoft.com/en-us/azure/storage/common/storage-introduction).
1313

14-
Stores the state as a Blob with the given Key within the Blob Container within [the Blob Storage Account](https://docs.microsoft.com/en-us/azure/storage/common/storage-introduction). This backend also supports state locking and consistency checking via native capabilities of Azure Blob Storage.
14+
This backend supports state locking and consistency checking with Azure Blob Storage native capabilities.
1515

1616
-> **Note:** By default the Azure Backend uses ADAL for authentication which is deprecated in favour of MSAL - MSAL can be used by setting `use_microsoft_graph` to `true`. **The default for this will change in Terraform 1.2**, so that MSAL authentication is used by default.
1717

0 commit comments

Comments
 (0)