From f521ba6cd747d8c44b35c3c2b22082e01357c756 Mon Sep 17 00:00:00 2001 From: Chris Arcand Date: Tue, 7 Dec 2021 15:07:22 -0600 Subject: [PATCH 01/19] Remove 'enhanced' backend type distinction As explained in the changes: The 'enhanced' backend terminology, which only truly pertains to the 'remote' backend with a single API (Terraform Cloud/Enterprise's), has been found to be a confusing vestige which need only be explained in the context of the 'remote' backend. These changes reorient the explanation(s) of backends to pertain more directly to their primary purpose, which is storage of state snapshots (and not implementing operations). That Terraform operations are still _implemented_ by the literal `Backend` and `Enhanced` interfaces is inconsequential a user of Terraform, an internal detail. --- docs/architecture.md | 29 ++--- internal/backend/backend.go | 7 +- .../settings/backends/artifactory.html.md | 4 +- .../settings/backends/azurerm.html.md | 4 +- .../settings/backends/configuration.html.md | 16 ++- .../language/settings/backends/consul.html.md | 2 - .../language/settings/backends/cos.html.md | 5 +- .../language/settings/backends/etcd.html.md | 4 +- .../language/settings/backends/etcdv3.html.md | 2 - .../language/settings/backends/gcs.html.md | 6 +- .../language/settings/backends/http.html.md | 10 +- .../language/settings/backends/index.html.md | 109 +++++------------- .../settings/backends/kubernetes.html.md | 4 +- .../language/settings/backends/manta.html.md | 4 +- .../language/settings/backends/oss.html.md | 4 +- .../language/settings/backends/pg.html.md | 2 - .../language/settings/backends/remote.html.md | 31 ++--- .../language/settings/backends/s3.html.md | 2 - .../language/settings/backends/swift.html.md | 4 +- .../language/settings/terraform-cloud.html.md | 37 ++++++ website/layouts/language.erb | 13 +-- 21 files changed, 138 insertions(+), 161 deletions(-) create mode 100644 website/docs/language/settings/terraform-cloud.html.md diff --git a/docs/architecture.md b/docs/architecture.md index 2f060b266..0c93b16f1 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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 diff --git a/internal/backend/backend.go b/internal/backend/backend.go index 9f1855eb2..4124b2abd 100644 --- a/internal/backend/backend.go +++ b/internal/backend/backend.go @@ -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 diff --git a/website/docs/language/settings/backends/artifactory.html.md b/website/docs/language/settings/backends/artifactory.html.md index 2e19dea89..d3cdf789f 100644 --- a/website/docs/language/settings/backends/artifactory.html.md +++ b/website/docs/language/settings/backends/artifactory.html.md @@ -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 diff --git a/website/docs/language/settings/backends/azurerm.html.md b/website/docs/language/settings/backends/azurerm.html.md index 9179a5551..632f6d2c6 100644 --- a/website/docs/language/settings/backends/azurerm.html.md +++ b/website/docs/language/settings/backends/azurerm.html.md @@ -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 via native capabilities of Azure Blob Storage. -> **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. diff --git a/website/docs/language/settings/backends/configuration.html.md b/website/docs/language/settings/backends/configuration.html.md index 886413e7e..dc848d3bc 100644 --- a/website/docs/language/settings/backends/configuration.html.md +++ b/website/docs/language/settings/backends/configuration.html.md @@ -5,11 +5,17 @@ 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. +Backend configuration is not needed when using Terraform Cloud, because +Terraform Cloud automatically manages state in the workspaces your configuration +is associated with. 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 +51,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 diff --git a/website/docs/language/settings/backends/consul.html.md b/website/docs/language/settings/backends/consul.html.md index d2f921454..dcb21df88 100644 --- a/website/docs/language/settings/backends/consul.html.md +++ b/website/docs/language/settings/backends/consul.html.md @@ -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). diff --git a/website/docs/language/settings/backends/cos.html.md b/website/docs/language/settings/backends/cos.html.md index cef18670c..4e8772f91 100644 --- a/website/docs/language/settings/backends/cos.html.md +++ b/website/docs/language/settings/backends/cos.html.md @@ -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. diff --git a/website/docs/language/settings/backends/etcd.html.md b/website/docs/language/settings/backends/etcd.html.md index 792b7354c..771b74d72 100644 --- a/website/docs/language/settings/backends/etcd.html.md +++ b/website/docs/language/settings/backends/etcd.html.md @@ -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 diff --git a/website/docs/language/settings/backends/etcdv3.html.md b/website/docs/language/settings/backends/etcdv3.html.md index 318a7b405..478f79d2c 100644 --- a/website/docs/language/settings/backends/etcdv3.html.md +++ b/website/docs/language/settings/backends/etcdv3.html.md @@ -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). diff --git a/website/docs/language/settings/backends/gcs.html.md b/website/docs/language/settings/backends/gcs.html.md index 1d869579e..172c1154a 100644 --- a/website/docs/language/settings/backends/gcs.html.md +++ b/website/docs/language/settings/backends/gcs.html.md @@ -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) diff --git a/website/docs/language/settings/backends/http.html.md b/website/docs/language/settings/backends/http.html.md index e87903c44..78eedcba9 100644 --- a/website/docs/language/settings/backends/http.html.md +++ b/website/docs/language/settings/backends/http.html.md @@ -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 diff --git a/website/docs/language/settings/backends/index.html.md b/website/docs/language/settings/backends/index.html.md index 5a8a75359..1188cfcdf 100644 --- a/website/docs/language/settings/backends/index.html.md +++ b/website/docs/language/settings/backends/index.html.md @@ -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 classifid as being 'standard' +or 'enhanced', where the latter term referred to the ability of the +[remote](/docs/language/settings/sbackends/remote.html) backend to not only store state but perform +Terraform operations. This classification has been removed, clarifying the primary purpose of +backends. See [Configuring Terraform Cloud](/docs/language/settings/configuring-terraform-cloud) 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. diff --git a/website/docs/language/settings/backends/kubernetes.html.md b/website/docs/language/settings/backends/kubernetes.html.md index 71d80e24f..20e3ecc1b 100644 --- a/website/docs/language/settings/backends/kubernetes.html.md +++ b/website/docs/language/settings/backends/kubernetes.html.md @@ -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 diff --git a/website/docs/language/settings/backends/manta.html.md b/website/docs/language/settings/backends/manta.html.md index ef82e5602..150b3633b 100644 --- a/website/docs/language/settings/backends/manta.html.md +++ b/website/docs/language/settings/backends/manta.html.md @@ -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 diff --git a/website/docs/language/settings/backends/oss.html.md b/website/docs/language/settings/backends/oss.html.md index e2a0adc12..a67ac94ff 100644 --- a/website/docs/language/settings/backends/oss.html.md +++ b/website/docs/language/settings/backends/oss.html.md @@ -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 diff --git a/website/docs/language/settings/backends/pg.html.md b/website/docs/language/settings/backends/pg.html.md index 934345f34..509f33c8e 100644 --- a/website/docs/language/settings/backends/pg.html.md +++ b/website/docs/language/settings/backends/pg.html.md @@ -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). diff --git a/website/docs/language/settings/backends/remote.html.md b/website/docs/language/settings/backends/remote.html.md index a011993a0..3e8d6ded3 100644 --- a/website/docs/language/settings/backends/remote.html.md +++ b/website/docs/language/settings/backends/remote.html.md @@ -8,17 +8,22 @@ description: |- # remote -**Kind: Enhanced** +-> **Note:** With the release of Terraform v1.1.0, 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. --> **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). +-> **Note:** This backend is unique among all other Terraform backends in that it has the ability to +execute operations for Terraform Cloud's [CLI-driven run workflow](/docs/cloud/run/cli.html), rather +than only store state snapshots. (The documentation used to refer to this as "enhanced" backend +behavior, but it's simpler to describe it as a quirk of the `remote` backend.) + +-> **Note:** The remote backend requires Terraform v0.11.13 or newer, and 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 +75,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 +195,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. diff --git a/website/docs/language/settings/backends/s3.html.md b/website/docs/language/settings/backends/s3.html.md index e043701f4..f5b2d2ee0 100644 --- a/website/docs/language/settings/backends/s3.html.md +++ b/website/docs/language/settings/backends/s3.html.md @@ -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 diff --git a/website/docs/language/settings/backends/swift.html.md b/website/docs/language/settings/backends/swift.html.md index 8bc3d783a..b53d83087 100644 --- a/website/docs/language/settings/backends/swift.html.md +++ b/website/docs/language/settings/backends/swift.html.md @@ -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 diff --git a/website/docs/language/settings/terraform-cloud.html.md b/website/docs/language/settings/terraform-cloud.html.md new file mode 100644 index 000000000..e0887c2a0 --- /dev/null +++ b/website/docs/language/settings/terraform-cloud.html.md @@ -0,0 +1,37 @@ +--- +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). These settings are only needed when +using Terraform CLI to interact with Terraform Cloud, and are ignored when interacting with +Terraform Cloud via version control or the API. + +Terraform Cloud is configured with a nested `cloud` block within the top-level +`terraform` block: + +```hcl +terraform { + cloud { + organization = "example_corp" + + workspaces { + tags = ["app"] + } + } +} +``` + +Using the Cloud integration is mutually exclusive of declaring any [state backend](/docs/language/settings/backends/index.html); that is, a configuration +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) +in the Terraform CLI docs for more information. diff --git a/website/layouts/language.erb b/website/layouts/language.erb index 91818808e..1fb37c0f3 100644 --- a/website/layouts/language.erb +++ b/website/layouts/language.erb @@ -850,6 +850,10 @@ Overview +
  • + Terraform Cloud +
    • +
  • Backends