Merge pull request #30102 from hashicorp/tfc-integration-docs-again
Add Terraform Cloud integration docs
This commit is contained in:
Chris Arcand
GitHub
commit
81136ce5e1
|
|
@ -61,29 +61,22 @@ Backends that are able to execute operations additionally implement
|
|||
the command-handling code calls `Operation` with the operation it has
|
||||
constructed, and then the backend is responsible for executing that action.
|
||||
|
||||
Most backends do _not_ implement this interface, and so the `command` package
|
||||
wraps these backends in an instance of
|
||||
Backends that execute operations, however, do so as an architectural implementation detail and not a
|
||||
general feature of backends. That is, the term 'backend' as a Terraform feature is used to refer to
|
||||
a plugin that determines where Terraform stores its state snapshots - only the default `local`
|
||||
backend and Terraform Cloud's backends (`remote`, `cloud`) perform operations.
|
||||
|
||||
Thus, most backends do _not_ implement this interface, and so the `command` package wraps these
|
||||
backends in an instance of
|
||||
[`local.Local`](https://pkg.go.dev/github.com/hashicorp/terraform/internal/backend/local#Local),
|
||||
causing the operation to be executed locally within the `terraform` process
|
||||
itself, which (at the time of writing) is currently the only way an operation
|
||||
can be executed.
|
||||
causing the operation to be executed locally within the `terraform` process itself.
|
||||
|
||||
## Backends
|
||||
|
||||
A _backend_ has a number of responsibilities in Terraform:
|
||||
A _backend_ determines where Terraform should store its state snapshots.
|
||||
|
||||
* Execute operations (e.g. plan, apply)
|
||||
* Store state
|
||||
* Store workspace-defined variables (in the future; not yet implemented)
|
||||
|
||||
As described above, the `local.Local` implementation -- named `local` from the
|
||||
user's standpoint -- is the only backend which implements _all_ functionality.
|
||||
Backends that cannot execute operations (at the time of writing, all except
|
||||
`local`) can be wrapped inside `local.Local` to perform operations locally
|
||||
while storing the [state](https://www.terraform.io/docs/state/index.html)
|
||||
elsewhere.
|
||||
|
||||
To execute an operation locally, the `local` backend uses a _state manager_
|
||||
As described above, the `local` backend also executes operations on behalf of most other
|
||||
backends. It uses a _state manager_
|
||||
(either
|
||||
[`statemgr.Filesystem`](https://pkg.go.dev/github.com/hashicorp/terraform/internal/states/statemgr#Filesystem) if the
|
||||
local backend is being used directly, or an implementation provided by whatever
|
||||
|
|
|
|||
|
|
@ -118,9 +118,10 @@ type Backend interface {
|
|||
|
||||
// Enhanced implements additional behavior on top of a normal backend.
|
||||
//
|
||||
// Enhanced backends allow customizing the behavior of Terraform operations.
|
||||
// This allows Terraform to potentially run operations remotely, load
|
||||
// configurations from external sources, etc.
|
||||
// 'Enhanced' backends are an implementation detail only, and are no longer reflected as an external
|
||||
// 'feature' of backends. In other words, backends refer to plugins for remote state snapshot
|
||||
// storage only, and the Enhanced interface here is a necessary vestige of the 'local' and
|
||||
// remote/cloud backends only.
|
||||
type Enhanced interface {
|
||||
Backend
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
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.
|
||||
|
||||
State-modification operations usually require using a local version of the
|
||||
Terraform CLI that is compatible with the Terraform version selected
|
||||
in the remote workspace settings. This prevents the
|
||||
local operation from creating a new state snapshot that the workspace's
|
||||
remote execution environment cannot decode.
|
||||
|
||||
We recommend against using this option unless absolutely necessary. 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.
|
||||
|
||||
|
|
@ -0,0 +1,28 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Using Terraform Cloud - Terraform CLI"
|
||||
---
|
||||
|
||||
# Using Terraform Cloud with Terraform CLI
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
> **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn.
|
||||
|
||||
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 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
|
||||
backend](/docs/cli/cloud/migrating.html) for details about switching to the CLI integration.
|
||||
|
||||
|
||||
## 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.
|
||||
|
|
@ -0,0 +1,85 @@
|
|||
---
|
||||
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. 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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Migrating from Local State or State Backends
|
||||
|
||||
> **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn.
|
||||
|
||||
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. You will need permission to manage workspaces in the destination Terraform Cloud organization. This process is interactive and self-documenting, and resembles
|
||||
moving between state backends.
|
||||
|
||||
Terraform may also prompt you 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 Terraform CLI-only workspaces, which represent
|
||||
multiple environments associated with the same configuration (e.g. production, staging, development),
|
||||
Terraform Cloud workspaces can represent totally independent configurations, and must have unique names within the Terraform Cloud organization.
|
||||
|
||||
Because of this, Terraform will prompt you to rename the working directory's workspaces
|
||||
according to a pattern relative to their existing names. This can indicate the fact that these specific workspaces share configuration. A typical strategy is
|
||||
`<COMPONENT>-<ENVIRONMENT>-<REGION>` (e.g., `networking-prod-us-east`,
|
||||
`networking-staging-us-east`). Refer to [Workspace
|
||||
Naming](/docs/cloud/workspaces/naming.html) in the Terraform Cloud documentation for more detail.
|
||||
|
||||
## 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. The local names shown for those workspaces will change to match their remote names.
|
||||
|
||||
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.
|
||||
|
||||
#### Single Workspace
|
||||
|
||||
If you were using a single workspace with the `name` argument, change the block
|
||||
label to `cloud`.
|
||||
|
||||
```diff
|
||||
terraform {
|
||||
- backend "remote" {
|
||||
+ cloud {
|
||||
organization = "my-org"
|
||||
|
||||
workspaces {
|
||||
name = "my-app-prod"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Multiple Workspaces
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
```diff
|
||||
terraform {
|
||||
- backend "remote" {
|
||||
+ cloud {
|
||||
organization = "my-org"
|
||||
|
||||
workspaces {
|
||||
- prefix = "my-app-"
|
||||
+ tags = ["app:mine"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,104 @@
|
|||
---
|
||||
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).
|
||||
|
||||
> **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn.
|
||||
|
||||
You must configure the following settings to use Terraform Cloud for a particular working directory:
|
||||
|
||||
- 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 also 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:** Unlike `.gitignore`, only the `.terraformignore` at the root of the configuration directory is considered.
|
||||
|
|
@ -25,6 +25,8 @@ resource.
|
|||
real-world object. Use this to preserve an object when renaming a resource, or
|
||||
when moving a resource into or out of a child module.
|
||||
|
||||
> **Hands On:** Try the [Use Configuration to Move Resources](https://learn.hashicorp.com/tutorials/terraform/move-config) on HashiCorp Learn.
|
||||
|
||||
- [The `terraform state rm` command](/docs/cli/commands/state/rm.html) tells
|
||||
Terraform to stop managing a resource as part of the current working directory
|
||||
and workspace, _without_ destroying the corresponding real-world object. (You
|
||||
|
|
|
|||
|
|
@ -68,12 +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
|
||||
[CLI-driven Runs](/docs/cloud/run/cli.html) in the Terraform Cloud docs.
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -8,8 +8,6 @@ description: |-
|
|||
|
||||
# artifactory
|
||||
|
||||
**Kind: Standard (with no locking)**
|
||||
|
||||
Stores the state as an artifact in a given repository in
|
||||
[Artifactory](https://www.jfrog.com/artifactory/).
|
||||
|
||||
|
|
@ -19,6 +17,8 @@ configurations may be kept at different subpaths within the repository.
|
|||
-> **Note:** The URL must include the path to the Artifactory installation.
|
||||
It will likely end in `/artifactory`.
|
||||
|
||||
This backend does **not** support [state locking](/docs/language/state/locking.html).
|
||||
|
||||
## Example Configuration
|
||||
|
||||
```hcl
|
||||
|
|
|
|||
|
|
@ -9,9 +9,9 @@ description: |-
|
|||
|
||||
# azurerm
|
||||
|
||||
**Kind: Standard (with state locking)**
|
||||
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).
|
||||
|
||||
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.
|
||||
This backend supports state locking and consistency checking with Azure Blob Storage native capabilities.
|
||||
|
||||
-> **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.
|
||||
|
||||
|
|
|
|||
|
|
@ -5,11 +5,14 @@ page_title: "Backend Configuration - Configuration Language"
|
|||
|
||||
# Backend Configuration
|
||||
|
||||
Each Terraform configuration can specify a backend, which defines where
|
||||
[state](/docs/language/state/index.html) snapshots are stored.
|
||||
|
||||
Each Terraform configuration can specify a backend, which defines exactly where
|
||||
and how operations are performed, where [state](/docs/language/state/index.html)
|
||||
snapshots are stored, etc. Most non-trivial Terraform configurations configure
|
||||
a remote backend so that multiple people can work with the same infrastructure.
|
||||
You do not need to configure a backend when using Terraform Cloud because
|
||||
Terraform Cloud automatically manages state in the workspaces associated with your configuration. If your configuration includes [a `cloud` block](/docs/language/settings/terraform-cloud.html), it cannot include a `backend` block.
|
||||
|
||||
Most non-trivial Terraform configurations store state remotely so that multiple
|
||||
people can work with the same infrastructure.
|
||||
|
||||
## Using a Backend Block
|
||||
|
||||
|
|
@ -45,7 +48,7 @@ See the list of backend types in the navigation sidebar for details about each s
|
|||
|
||||
### Default Backend
|
||||
|
||||
If a configuration includes no backend block, Terraform defaults to using the `local` backend, which performs operations on the local system and stores state as a plain file in the current working directory.
|
||||
If a configuration includes no backend block, Terraform defaults to using the `local` backend, which stores state as a plain file in the current working directory.
|
||||
|
||||
## Initialization
|
||||
|
||||
|
|
|
|||
|
|
@ -8,8 +8,6 @@ description: |-
|
|||
|
||||
# consul
|
||||
|
||||
**Kind: Standard (with locking)**
|
||||
|
||||
Stores the state in the [Consul](https://www.consul.io/) KV store at a given path.
|
||||
|
||||
This backend supports [state locking](/docs/language/state/locking.html).
|
||||
|
|
|
|||
|
|
@ -8,10 +8,9 @@ description: |-
|
|||
|
||||
# COS
|
||||
|
||||
**Kind: Standard (with locking)**
|
||||
|
||||
Stores the state as an object in a configurable prefix in a given bucket on [Tencent Cloud Object Storage](https://intl.cloud.tencent.com/product/cos) (COS).
|
||||
This backend also supports [state locking](/docs/language/state/locking.html).
|
||||
|
||||
This backend supports [state locking](/docs/language/state/locking.html).
|
||||
|
||||
~> **Warning!** It is highly recommended that you enable [Object Versioning](https://intl.cloud.tencent.com/document/product/436/19883)
|
||||
on the COS bucket to allow for state recovery in the case of accidental deletions and human error.
|
||||
|
|
|
|||
|
|
@ -8,10 +8,10 @@ description: |-
|
|||
|
||||
# etcd
|
||||
|
||||
**Kind: Standard (with no locking)**
|
||||
|
||||
Stores the state in [etcd 2.x](https://coreos.com/etcd/docs/latest/v2/README.html) at a given path.
|
||||
|
||||
This backend does **not** support [state locking](/docs/language/state/locking.html).
|
||||
|
||||
## Example Configuration
|
||||
|
||||
```hcl
|
||||
|
|
|
|||
|
|
@ -8,8 +8,6 @@ description: |-
|
|||
|
||||
# etcdv3
|
||||
|
||||
**Kind: Standard (with locking)**
|
||||
|
||||
Stores the state in the [etcd](https://etcd.io/) KV store with a given prefix.
|
||||
|
||||
This backend supports [state locking](/docs/language/state/locking.html).
|
||||
|
|
|
|||
|
|
@ -8,10 +8,10 @@ description: |-
|
|||
|
||||
# gcs
|
||||
|
||||
**Kind: Standard (with locking)**
|
||||
|
||||
Stores the state as an object in a configurable prefix in a pre-existing bucket on [Google Cloud Storage](https://cloud.google.com/storage/) (GCS).
|
||||
This backend also supports [state locking](/docs/language/state/locking.html). The bucket must exist prior to configuring the backend.
|
||||
The bucket must exist prior to configuring the backend.
|
||||
|
||||
This backend supports [state locking](/docs/language/state/locking.html).
|
||||
|
||||
~> **Warning!** It is highly recommended that you enable
|
||||
[Object Versioning](https://cloud.google.com/storage/docs/object-versioning)
|
||||
|
|
|
|||
|
|
@ -8,15 +8,15 @@ description: |-
|
|||
|
||||
# http
|
||||
|
||||
**Kind: Standard (with optional locking)**
|
||||
|
||||
Stores the state using a simple [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) client.
|
||||
|
||||
State will be fetched via GET, updated via POST, and purged with DELETE. The method used for updating is configurable.
|
||||
|
||||
When locking support is enabled it will use LOCK and UNLOCK requests providing the lock info in the body. The endpoint should
|
||||
return a 423: Locked or 409: Conflict with the holding lock info when it's already taken, 200: OK for success. Any other status
|
||||
will be considered an error. The ID of the holding lock info will be added as a query parameter to state updates requests.
|
||||
This backend optionally supports [state locking](/docs/language/state/locking.html). When locking
|
||||
support is enabled it will use LOCK and UNLOCK requests providing the lock info in the body. The
|
||||
endpoint should return a 423: Locked or 409: Conflict with the holding lock info when it's already
|
||||
taken, 200: OK for success. Any other status will be considered an error. The ID of the holding lock
|
||||
info will be added as a query parameter to state updates requests.
|
||||
|
||||
## Example Usage
|
||||
|
||||
|
|
|
|||
|
|
@ -1,14 +1,16 @@
|
|||
---
|
||||
layout: "language"
|
||||
page_title: "Backend Overview - Configuration Language"
|
||||
description: "A backend defines where and how Terraform performs operations, such as where it stores state files. Learn about recommended backends and how backends work."
|
||||
description: "A backend defines where Terraform stores its state. Learn about how backends work."
|
||||
---
|
||||
|
||||
# Backends
|
||||
|
||||
Each Terraform configuration can specify a backend, which defines where
|
||||
and how operations are performed, where [state](/docs/language/state/index.html)
|
||||
snapshots are stored, etc.
|
||||
Backends define where Terraform's [state](/docs/language/state/index.html) snapshots are stored.
|
||||
|
||||
A given Terraform configuration can either specify a backend,
|
||||
[integrate with Terraform Cloud](/docs/language/settings/terraform-cloud.html),
|
||||
or do neither and default to storing state locally.
|
||||
|
||||
The rest of this page introduces the concept of backends; the other pages in
|
||||
this section document how to configure and use backends.
|
||||
|
|
@ -20,92 +22,37 @@ this section document how to configure and use backends.
|
|||
documenting its behavior and available settings. See the navigation sidebar
|
||||
for a complete list.
|
||||
|
||||
## Recommended Backends
|
||||
|
||||
- If you are still learning how to use Terraform, we recommend using the default
|
||||
`local` backend, which requires no configuration.
|
||||
- If you and your team are using Terraform to manage meaningful infrastructure,
|
||||
we recommend using the `remote` backend with [Terraform Cloud](/docs/cloud/index.html)
|
||||
or [Terraform Enterprise](/docs/enterprise/index.html).
|
||||
|
||||
## Where Backends are Used
|
||||
|
||||
Backend configuration is only used by [Terraform CLI](/docs/cli/index.html).
|
||||
Terraform Cloud and Terraform Enterprise always use their own state storage when
|
||||
performing Terraform runs, so they ignore any backend block in the
|
||||
configuration.
|
||||
|
||||
But since it's common to
|
||||
[use Terraform CLI alongside Terraform Cloud](/docs/cloud/run/cli.html)
|
||||
(and since certain state operations, like [tainting](/docs/cli/commands/taint.html),
|
||||
can only be performed on the CLI), we recommend that Terraform Cloud users
|
||||
include a backend block in their configurations and configure the `remote`
|
||||
backend to use the relevant Terraform Cloud workspace(s).
|
||||
|
||||
## Where Backends Come From
|
||||
|
||||
Terraform includes a built-in selection of backends; this selection has changed
|
||||
over time, but does not change very often.
|
||||
|
||||
The built-in backends are the only backends. You cannot load additional backends
|
||||
as plugins.
|
||||
|
||||
## What Backends Do
|
||||
|
||||
There are two areas of Terraform's behavior that are determined by the backend:
|
||||
Backends primarily determine where Terraform stores its [state](/docs/language/state/index.html).
|
||||
Terraform uses this persisted [state](/docs/language/state/index.html) data to keep track of the
|
||||
resources it manages. Since it needs the state in order to know which real-world infrastructure
|
||||
objects correspond to the resources in a configuration, everyone working with a given collection of
|
||||
infrastructure resources must be able to access the same state data.
|
||||
|
||||
- Where state is stored.
|
||||
- Where operations are performed.
|
||||
|
||||
### State
|
||||
|
||||
Terraform uses persistent [state](/docs/language/state/index.html) data to keep track of
|
||||
the resources it manages. Since it needs the state in order to know which
|
||||
real-world infrastructure objects correspond to the resources in a
|
||||
configuration, everyone working with a given collection of infrastructure
|
||||
resources must be able to access the same state data.
|
||||
|
||||
The `local` backend stores state as a local file on disk, but every other
|
||||
backend stores state in a remote service of some kind, which allows multiple
|
||||
people to access it. Accessing state in a remote service generally requires some
|
||||
kind of access credentials, since state data contains extremely sensitive
|
||||
information.
|
||||
By default, Terraform implicitly uses a backend called
|
||||
[`local`](/docs/language/settings/backends/local.html) to store state as a local file on disk.
|
||||
Every other backend stores state in a remote service of some kind, which allows multiple people to
|
||||
access it. Accessing state in a remote service generally requires some kind of access credentials,
|
||||
since state data contains extremely sensitive information.
|
||||
|
||||
Some backends act like plain "remote disks" for state files; others support
|
||||
_locking_ the state while operations are being performed, which helps prevent
|
||||
conflicts and inconsistencies.
|
||||
|
||||
### Operations
|
||||
-> **Note:** In Terraform versions prior to 1.1.0, backends were also classified as being 'standard'
|
||||
or 'enhanced', where the latter term referred to the ability of the
|
||||
[remote](/docs/language/settings/sbackends/remote.html) backend to store state and perform
|
||||
Terraform operations. This classification has been removed, clarifying the primary purpose of
|
||||
backends. Refer to [Configuring Terraform Cloud](/docs/language/settings/configuring-terraform-cloud) for details about how to
|
||||
store state, execute remote operations, and use Terraform Cloud directly from Terraform.
|
||||
|
||||
"Operations" refers to performing API requests against infrastructure services
|
||||
in order to create, read, update, or destroy resources. Not every `terraform`
|
||||
subcommand performs API operations; many of them only operate on state data.
|
||||
## Available Backends
|
||||
|
||||
Only two backends actually perform operations: `local` and `remote`.
|
||||
Terraform includes a built-in selection of backends, which are listed in the
|
||||
navigation sidebar. This selection has changed over time, but does not change
|
||||
very often.
|
||||
|
||||
The `local` backend performs API operations directly from the machine where the
|
||||
`terraform` command is run. Whenever you use a backend other than `local` or
|
||||
`remote`, Terraform uses the `local` backend for operations; it only uses the
|
||||
configured backend for state storage.
|
||||
The built-in backends are the only backends. You cannot load additional backends
|
||||
as plugins.
|
||||
|
||||
The `remote` backend can perform API operations remotely, using Terraform Cloud
|
||||
or Terraform Enterprise. When running remote operations, the local `terraform`
|
||||
command displays the output of the remote actions as though they were being
|
||||
performed locally, but only the remote system requires cloud credentials or
|
||||
network access to the resources being managed.
|
||||
|
||||
Remote operations are optional for the `remote` backend; the settings for the
|
||||
target Terraform Cloud workspace determine whether operations run remotely or
|
||||
locally. If local operations are configured, Terraform uses the `remote` backend
|
||||
for state and the `local` backend for operations, like with the other state
|
||||
backends.
|
||||
|
||||
### Backend Types
|
||||
|
||||
Terraform's backends are divided into two main types, according to how they
|
||||
handle state and operations:
|
||||
|
||||
- **Enhanced** backends can both store state and perform operations. There are
|
||||
only two enhanced backends: `local` and `remote`.
|
||||
- **Standard** backends only store state, and rely on the `local` backend for
|
||||
performing operations.
|
||||
|
|
|
|||
|
|
@ -10,9 +10,9 @@ description: |-
|
|||
|
||||
-> **Note:** This backend is limited by Kubernetes' maximum Secret size of 1MB. See [Secret restrictions](https://kubernetes.io/docs/concepts/configuration/secret/#restrictions) for details.
|
||||
|
||||
**Kind: Standard (with locking)**
|
||||
Stores the state in a [Kubernetes secret](https://kubernetes.io/docs/concepts/configuration/secret/).
|
||||
|
||||
Stores the state in a [Kubernetes secret](https://kubernetes.io/docs/concepts/configuration/secret/) with locking done using a Lease resource.
|
||||
This backend supports [state locking](/docs/language/state/locking.html), with locking done using a Lease resource.
|
||||
|
||||
## Example Configuration
|
||||
|
||||
|
|
|
|||
|
|
@ -8,10 +8,10 @@ description: |-
|
|||
|
||||
# manta
|
||||
|
||||
**Kind: Standard (with locking within Manta)**
|
||||
|
||||
Stores the state as an artifact in [Manta](https://www.joyent.com/manta).
|
||||
|
||||
This backend supports [state locking](/docs/language/state/locking.html), with locking within Manta.
|
||||
|
||||
## Example Configuration
|
||||
|
||||
```hcl
|
||||
|
|
|
|||
|
|
@ -8,14 +8,14 @@ description: |-
|
|||
|
||||
# OSS
|
||||
|
||||
**Kind: Standard (with locking via TableStore)**
|
||||
|
||||
Stores the state as a given key in a given bucket on Stores
|
||||
[Alibaba Cloud OSS](https://www.alibabacloud.com/help/product/31815.htm).
|
||||
This backend also supports state locking and consistency checking via
|
||||
[Alibaba Cloud Table Store](https://www.alibabacloud.com/help/doc-detail/27280.htm), which can be enabled by setting
|
||||
the `tablestore_table` field to an existing TableStore table name.
|
||||
|
||||
This backend supports [state locking](/docs/language/state/locking.html) via TableStore.
|
||||
|
||||
-> **Note:** The OSS backend is available from terraform version 0.12.2.
|
||||
|
||||
## Example Configuration
|
||||
|
|
|
|||
|
|
@ -8,8 +8,6 @@ description: |-
|
|||
|
||||
# pg
|
||||
|
||||
**Kind: Standard (with locking)**
|
||||
|
||||
Stores the state in a [Postgres database](https://www.postgresql.org) version 10 or newer.
|
||||
|
||||
This backend supports [state locking](/docs/language/state/locking.html).
|
||||
|
|
|
|||
|
|
@ -8,17 +8,15 @@ description: |-
|
|||
|
||||
# remote
|
||||
|
||||
**Kind: Enhanced**
|
||||
-> **Note:** The remote backend was introduced in Terraform v0.11.13 and Terraform Enterprise v201809-1. As of Terraform v1.1.0 and Terraform Enterprise v202201-1, **we recommend using the Terraform Cloud's built-in [`cloud` integration](/docs/language/settings/terraform-cloud.html)** instead of this backend. The `cloud` option includes an improved user experience and more features.
|
||||
|
||||
|
||||
The remote backend is unique among all other Terraform backends because it can both store state snapshots and execute operations for Terraform Cloud's [CLI-driven run workflow](/docs/cloud/run/cli.html). It used to be called an "enhanced" backend.
|
||||
|
||||
-> **Note:** We recommend using Terraform v0.11.13 or newer with this
|
||||
backend. This backend requires either a Terraform Cloud account on
|
||||
[app.terraform.io](https://app.terraform.io) or a Terraform Enterprise instance
|
||||
(version v201809-1 or newer).
|
||||
|
||||
The remote backend stores Terraform state and may be used to run operations in Terraform Cloud.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
|
|
@ -70,16 +68,16 @@ 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}`](/docs/language/state/workspaces.html#current-workspace-interpolation)
|
||||
interpolation sequence should be removed from Terraform configurations that run
|
||||
Additionally, the [`terraform.workspace`](/docs/language/state/workspaces.html#referencing-the-current-workspace-name)
|
||||
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
|
||||
each Terraform Cloud workspace currently only uses the single `default` Terraform
|
||||
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.)
|
||||
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.
|
||||
|
|
@ -190,7 +188,7 @@ The following configuration options are supported:
|
|||
workspace names are used in Terraform Cloud, and the short names
|
||||
(minus the prefix) are used on the command line for Terraform CLI workspaces.
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -8,8 +8,6 @@ description: |-
|
|||
|
||||
# S3
|
||||
|
||||
**Kind: Standard (with locking via DynamoDB)**
|
||||
|
||||
Stores the state as a given key in a given bucket on
|
||||
[Amazon S3](https://aws.amazon.com/s3/).
|
||||
This backend also supports state locking and consistency checking via
|
||||
|
|
|
|||
|
|
@ -8,10 +8,10 @@ description: |-
|
|||
|
||||
# swift
|
||||
|
||||
**Kind: Standard (with locking)**
|
||||
|
||||
Stores the state as an artifact in [Swift](http://docs.openstack.org/developer/swift/latest/).
|
||||
|
||||
This backend supports [state locking](/docs/language/state/locking.html).
|
||||
|
||||
~> Warning! It is highly recommended that you enable [Object Versioning](https://docs.openstack.org/developer/swift/latest/overview_object_versioning.html) by setting the [`archive_container`](https://www.terraform.io/docs/language/settings/backends/swift.html#archive_container) configuration. This allows for state recovery in the case of accidental deletions and human error.
|
||||
|
||||
## Example Configuration
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
layout: "language"
|
||||
page_title: "Terraform Settings - Configuration Language"
|
||||
sidebar_current: "docs-config-terraform"
|
||||
description: "The terraform block allows you to configure Terraform behavior, including the Terraform version, backend, and required providers."
|
||||
description: "The terraform block allows you to configure Terraform behavior, including the Terraform version, backend, integration with Terraform Cloud, and required providers."
|
||||
---
|
||||
|
||||
# Terraform Settings
|
||||
|
|
@ -29,9 +29,19 @@ etc, and may not use any of the Terraform language built-in functions.
|
|||
The various options supported within a `terraform` block are described in the
|
||||
following sections.
|
||||
|
||||
## Configuring Terraform Cloud
|
||||
|
||||
The nested `cloud` block configures Terraform Cloud for enabling its
|
||||
[CLI-driven run workflow](/docs/cloud/run/cli.html).
|
||||
|
||||
- Refer to [Terraform Cloud Configuration](/docs/language/settings/terraform-cloud.html) for a summary of the `cloud` block's syntax.
|
||||
|
||||
- Refer to [Using Terraform Cloud](/docs/cli/cloud/index.html) in the
|
||||
Terraform CLI documentation for complete details about how to initialize and configure the Terraform Cloud CLI integration.
|
||||
|
||||
## Configuring a Terraform Backend
|
||||
|
||||
The nested `backend` block configures which backend Terraform should use.
|
||||
The nested `backend` block configures which state backend Terraform should use.
|
||||
|
||||
The syntax and behavior of the `backend` block is described in [Backend
|
||||
Configuration](/docs/language/settings/backends/configuration.html).
|
||||
|
|
|
|||
|
|
@ -0,0 +1,33 @@
|
|||
---
|
||||
layout: "language"
|
||||
page_title: "Terraform Cloud Configuration - Terraform Settings - Configuration Language"
|
||||
sidebar_current: "docs-config-terraform"
|
||||
description: "The nested `cloud` block configures Terraform's integration with Terraform Cloud."
|
||||
---
|
||||
|
||||
# Terraform Cloud Configuration
|
||||
|
||||
The main module of a Terraform configuration can integrate with Terraform Cloud to enable its
|
||||
[CLI-driven run workflow](/docs/cloud/run/cli.html). You only need to configure these settings when you want to use Terraform CLI to interact with Terraform Cloud. Terraform Cloud ignores them when interacting with
|
||||
Terraform through version control or the API.
|
||||
|
||||
> **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn.
|
||||
|
||||
You can configure the Terraform Cloud CLI integration by adding a nested `cloud` block within the top-level
|
||||
`terraform` block:
|
||||
|
||||
```hcl
|
||||
terraform {
|
||||
cloud {
|
||||
organization = "example_corp"
|
||||
|
||||
workspaces {
|
||||
tags = ["app"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You cannot use the CLI integration and a [state backend](/docs/language/settings/backends/index.html) in the same configuration; they are mutually exclusive. A configuration can only provide one `cloud` block and the `cloud` block cannot refer to named values like input variables, locals, or data source attributes.
|
||||
|
||||
Refer to [Using Terraform Cloud](/docs/cli/cloud/index.html) in the Terraform CLI docs for more information.
|
||||
|
|
@ -19,8 +19,8 @@ which can then be shared between all members of a team. Terraform supports
|
|||
storing state in [Terraform Cloud](https://www.hashicorp.com/products/terraform/),
|
||||
[HashiCorp Consul](https://www.consul.io/), Amazon S3, Azure Blob Storage, Google Cloud Storage, Alibaba Cloud OSS, and more.
|
||||
|
||||
Remote state is implemented by a [backend](/docs/language/settings/backends/index.html),
|
||||
which you can configure in your configuration's root module.
|
||||
Remote state is implemented by a [backend](/docs/language/settings/backends/index.html) or by
|
||||
Terraform Cloud, both of which you can configure in your configuration's root module.
|
||||
|
||||
## Delegation and Teamwork
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -334,6 +334,27 @@
|
|||
</ul>
|
||||
</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>
|
||||
<a href="#">Automating Terraform</a>
|
||||
<ul class="nav">
|
||||
|
|
@ -565,7 +586,7 @@
|
|||
<li>
|
||||
<a href="/docs/internals/remote-service-discovery.html">Remote Service Discovery</a>
|
||||
</li>
|
||||
|
||||
|
||||
<li>
|
||||
<a href="/docs/internals/graph.html">Resource Graph</a>
|
||||
</li>
|
||||
|
|
|
|||
|
|
@ -850,6 +850,10 @@
|
|||
<a href="/docs/language/settings/index.html">Overview</a>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<a href="/docs/language/settings/terraform-cloud.html">Terraform Cloud</a>
|
||||
</li>
|
||||
|
||||
<li>
|
||||
<a href="#">Backends</a>
|
||||
<ul class="nav">
|
||||
|
|
@ -862,7 +866,7 @@
|
|||
</li>
|
||||
|
||||
<li>
|
||||
<a href="#">Enhanced Backends</a>
|
||||
<a href="#">Available Backends</a>
|
||||
<ul class="nav nav-auto-expand">
|
||||
<li>
|
||||
<a href="/docs/language/settings/backends/local.html">local</a>
|
||||
|
|
@ -870,13 +874,6 @@
|
|||
<li>
|
||||
<a href="/docs/language/settings/backends/remote.html">remote</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
||||
|
||||
<li>
|
||||
<a href="#">Standard Backends</a>
|
||||
<ul class="nav nav-auto-expand">
|
||||
<li>
|
||||
<a href="/docs/language/settings/backends/artifactory.html">artifactory</a>
|
||||
</li>
|
||||
|
|
|
|||
Loading…
Reference in New Issue