IntenseWebs/opentofu
3
0
Fork 0
mirror of https://github.com/opentofu/opentofu.git synced 2024-12-25 16:31:10 -06:00
Code Issues Packages Projects Releases Wiki Activity

Remove overview backends page; add sensitive credentials warning to config page

Browse Source
This commit is contained in:
Laura Pacilio 2022-06-08 16:17:27 -04:00
parent 2f1a8bbbd8
commit 89dbd6a26b
3 changed files with 29 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
website/data/language-nav-data.json
View File

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

38
website/docs/language/settings/backends/configuration.mdx
View File

@ -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, HashiCorp 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).
### Managing Credentials
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 sensitive credentials and other 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. 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.
Configuration stored in a plan file takes precedence over other configuration. This may cause authentication issues if credentials change between creating and applying plans. For example, this can occur in automated environments where credentials are scoped to the duration of a job.
### 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

58
website/docs/language/settings/backends/index.mdx
View File

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