Merge pull request #31213 from hashicorp/add-warnings-backends

Revise Backends Config Page

website/data/language-nav-data.json

@@ -903,7 +903,6 @@
       {
         "title": "Backends",
         "routes": [
-          { "title": "Overview", "path": "settings/backends" },
           {
             "title": "Backend Configuration",
             "path": "settings/backends/configuration"

website/docs/language/settings/backends/artifactory.mdx

@@ -45,7 +45,9 @@ data "terraform_remote_state" "foo" {
 }
 ```
 
-## Configuration variables
+## Configuration Variables
+
+!> **Warning:**  We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
 
 The following configuration options / environment variables are supported:
 

website/docs/language/settings/backends/azurerm.mdx

@@ -230,7 +230,10 @@ data "terraform_remote_state" "foo" {
 }
 ```
 
-## Configuration variables
+## Configuration Variables
+
+!> **Warning:**  We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
+
 
 The following configuration options are supported:
 

website/docs/language/settings/backends/configuration.mdx

@@ -4,19 +4,27 @@ page_title: Backend Configuration - Configuration Language
 
 # Backend Configuration
 
-Each Terraform configuration can specify a backend, which defines where
-[state](/language/state) snapshots are stored.
+A backend defines where Terraform stores its [state](/language/state) data files.
 
-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](/language/settings/terraform-cloud), it cannot include a `backend` block.
+Terraform uses persisted state data to keep track of the resources it manages. Most non-trivial Terraform configurations either [integrate with Terraform Cloud](/language/settings/terraform-cloud) or use a backend to store state remotely. This lets multiple people access the state data and work together on that collection of infrastructure resources.
 
-Most non-trivial Terraform configurations store state remotely so that multiple
-people can work with the same infrastructure.
+This page describes how to configure a backend by adding the [`backend` block](#using-a-backend-block) to your configuration.
+
+-> **Note:** In Terraform versions before 1.1.0, we classified backends as standard or enhanced. The enhanced label differentiated the [`remote` backend](/language/settings/backends/remote), which could both store state and perform Terraform operations. This classification has been removed. Refer to [Using Terraform Cloud](/cli/cloud) for details about storing state, executing remote operations, and using Terraform Cloud directly from Terraform.
+
+## Available Backends
+
+By default, Terraform uses a backend called [`local`](/language/settings/backends/local), which stores state as a local file on disk. You can also configure one of the built-in backends listed in the documentation sidebar.
+
+Some of these backends act like plain remote disks for state files, while others support locking the state while operations are being performed. This helps prevent conflicts and inconsistencies. The built-in backends listed are the only backends. You cannot load additional backends as plugins.
 
 ## Using a Backend Block
 
-Backends are configured with a nested `backend` block within the top-level
-`terraform` block:
+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](/language/settings/terraform-cloud), it cannot include a `backend` block.
+
+To configure a backend, add a nested `backend` block within the top-level
+`terraform` block. The following example configures the `remote` backend.
 
 ```hcl
 terraform {
@@ -35,6 +43,18 @@ There are some important limitations on backend configuration:
 - A configuration can only provide one backend block.
 - A backend block cannot refer to named values (like input variables, locals, or data source attributes).
 
+### Credentials and Sensitive Data
+
+Backends store state in a remote service, which allows multiple people to access it. Accessing remote state generally requires access credentials, since state data contains extremely sensitive information.
+
+!> **Warning:**  We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. This can leak sensitive credentials.
+
+Terraform writes the backend configuration in plain text in two separate files.
+- The `.terraform/terraform.tfstate` file contains the backend configuration for the current working directory.
+- All plan files capture the information in `.terraform/terraform.tfstate` at the time the plan was created. This helps ensure Terraform is applying the plan to correct set of infrastructure.
+
+When applying a plan that you previously saved to a file, Terraform uses the backend configuration stored in that file instead of the current backend settings. If that configuration contains time-limited credentials, they may expire before you finish applying the plan. Use environment variables to pass credentials when you need to use different values between the plan and apply steps.
+
 ### Backend Types
 
 The block label of the backend block (`"remote"`, in the example above) indicates which backend type to use. Terraform has a built-in selection of backends, and the configured backend must be available in the version of Terraform you are using.
@@ -43,7 +63,7 @@ The arguments used in the block's body are specific to the chosen backend type;
 
 Some backends allow providing access credentials directly as part of the configuration for use in unusual situations, for pragmatic reasons. However, in normal use we _do not_ recommend including access credentials as part of the backend configuration. Instead, leave those arguments completely unset and provide credentials via the credentials files or environment variables that are conventional for the target system, as described in the documentation for each backend.
 
-See the list of backend types in the navigation sidebar for details about each supported backend type and its configuration arguments.
+Refer to the list of backend types in the navigation sidebar for details about each supported backend type and its configuration arguments.
 
 ### Default Backend
 

website/docs/language/settings/backends/consul.mdx

@@ -35,7 +35,9 @@ data "terraform_remote_state" "foo" {
 }
 ```
 
-## Configuration variables
+## Configuration Variables
+
+!> **Warning:**  We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
 
 The following configuration options / environment variables are supported:
 

website/docs/language/settings/backends/cos.mdx

@@ -45,7 +45,9 @@ data "terraform_remote_state" "foo" {
 }
 ```
 
-## Configuration variables
+## Configuration Variables
+
+!> **Warning:**  We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
 
 The following configuration options or environment variables are supported:
 

website/docs/language/settings/backends/etcd.mdx

@@ -32,7 +32,9 @@ data "terraform_remote_state" "foo" {
 }
 ```
 
-## Configuration variables
+## Configuration Variables
+
+!> **Warning:**  We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
 
 The following configuration options are supported:
 

website/docs/language/settings/backends/etcdv3.mdx

@@ -37,7 +37,9 @@ data "terraform_remote_state" "foo" {
 }
 ```
 
-## Configuration variables
+## Configuration Variables
+
+!> **Warning:**  We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both state and plan files. Refer to [Credentials and Sensitive Data](/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
 
 The following configuration options / environment variables are supported:
 

website/docs/language/settings/backends/gcs.mdx

@@ -73,7 +73,9 @@ the path of the service account key. Terraform will use that key for authenticat
 
 Terraform can impersonate a Google Service Account as described [here](https://cloud.google.com/iam/docs/creating-short-lived-service-account-credentials). A valid credential must be provided as mentioned in the earlier section and that identity must have the `roles/iam.serviceAccountTokenCreator` role on the service account you are impersonating.
 
-## Configuration variables
+## Configuration Variables
+
+!> **Warning:**  We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
 
 The following configuration options are supported:
 

website/docs/language/settings/backends/http.mdx

@@ -38,7 +38,9 @@ data "terraform_remote_state" "foo" {
 }
 ```
 
-## Configuration variables
+## Configuration Variables
+
+!> **Warning:**  We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
 
 The following configuration options / environment variables are supported:
 

website/docs/language/settings/backends/index.mdx

@@ -1,58 +0,0 @@
----
-page_title: Backend Overview - Configuration Language
-description: >-
-  A backend defines where Terraform stores its state. Learn about how backends
-  work.
----
-
-# Backends
-
-Backends define where Terraform's [state](/language/state) snapshots are stored.
-
-A given Terraform configuration can either specify a backend,
-[integrate with Terraform Cloud](/language/settings/terraform-cloud),
-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.
-
-- [Backend Configuration](/language/settings/backends/configuration) documents the form
-  of a `backend` block, which selects and configures a backend for a
-  Terraform configuration.
-- This section also includes a page for each of Terraform's built-in backends,
-  documenting its behavior and available settings. See the navigation sidebar
-  for a complete list.
-
-## What Backends Do
-
-Backends primarily determine where Terraform stores its [state](/language/state).
-Terraform uses this persisted [state](/language/state) 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.
-
-By default, Terraform implicitly uses a backend called
-[`local`](/language/settings/backends/local) 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.
-
--> **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 backend](/language/settings/backends/remote) to store state and perform
-Terraform operations. This classification has been removed, clarifying the primary purpose of
-backends. Refer to [Using Terraform Cloud](/cli/cloud) for details about how to
-store state, execute remote operations, and use Terraform Cloud directly from Terraform.
-
-## Available Backends
-
-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 built-in backends are the only backends. You cannot load additional backends
-as plugins.

website/docs/language/settings/backends/kubernetes.mdx

@@ -44,7 +44,9 @@ data "terraform_remote_state" "foo" {
 }
 ```
 
-## Configuration variables
+## Configuration Variables
+
+!> **Warning:**  We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
 
 The following configuration options are supported:
 

website/docs/language/settings/backends/manta.mdx

@@ -35,7 +35,9 @@ data "terraform_remote_state" "foo" {
 }
 ```
 
-## Configuration variables
+## Configuration Variables
+
+!> **Warning:**  We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
 
 The following configuration options are supported:
 

website/docs/language/settings/backends/oss.mdx

@@ -69,7 +69,9 @@ data "terraform_remote_state" "network" {
 }
 ```
 
-## Configuration variables
+## Configuration Variables
+
+!> **Warning:**  We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
 
 The following configuration options or environment variables are supported:
 

website/docs/language/settings/backends/pg.mdx

@@ -64,6 +64,8 @@ data "terraform_remote_state" "network" {
 
 ## Configuration Variables
 
+!> **Warning:**  We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
+
 The following configuration options or environment variables are supported:
 
 - `conn_str` - (Required) Postgres connection string; a `postgres://` URL

website/docs/language/settings/backends/remote.mdx

@@ -173,7 +173,9 @@ data "terraform_remote_state" "foo" {
 }
 ```
 
-## Configuration variables
+## Configuration Variables
+
+!> **Warning:**  We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
 
 The following configuration options are supported:
 

website/docs/language/settings/backends/s3.mdx

@@ -142,6 +142,8 @@ This backend requires the configuration of the AWS Region and S3 state storage.
 
 ### Credentials and Shared Configuration
 
+!> **Warning:**  We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
+
 The following configuration is required:
 
 * `region` - (Required) AWS Region of the S3 Bucket and DynamoDB Table (if used). This can also be sourced from the `AWS_DEFAULT_REGION` and `AWS_REGION` environment variables.
@@ -411,7 +413,7 @@ to only a single state object within an S3 bucket is shown below:
 ```
 
 It is also possible to apply fine-grained access control to the DynamoDB
-table used for locking. When Terraform puts the state lock in place during `terraform plan`, it stores the full state file as a document and sets the s3 object key as the partition key for the document. After the state lock is released, Terraform places a digest of the updated state file in DynamoDB. The key is similar to the one for the original state file, but is suffixed with `-md5`. 
+table used for locking. When Terraform puts the state lock in place during `terraform plan`, it stores the full state file as a document and sets the s3 object key as the partition key for the document. After the state lock is released, Terraform places a digest of the updated state file in DynamoDB. The key is similar to the one for the original state file, but is suffixed with `-md5`.
 
 The example below shows a simple IAM policy that allows the backend operations role to perform these operations:
 

website/docs/language/settings/backends/swift.mdx

@@ -39,7 +39,9 @@ data "terraform_remote_state" "foo" {
 }
 ```
 
-## Configuration variables
+## Configuration Variables
+
+!> **Warning:**  We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
 
 The following configuration options are supported: