mirror of https://github.com/hashicorp/terraform
During the language/CLI docs reorg, we noticed several pages that were no longer viable; some were redundant, some useless, and some just very obsolete. Since we were trying to avoid breaking links at the time, we opted to remove them from the navs and leave them as "ghost pages" — still accessible, but not findable. This commit finally cleans these ghosts up and updates any remaining links to relevant modern pages. Bustin' makes me feel good. 👻🚫pull/27560/head
Nick Fagerlund
5 years ago
parent
7a8dd326c6
commit
8cfcd82be3
@ -1,147 +0,0 @@
|
||||
---
|
||||
layout: "language"
|
||||
page_title: "Backends: Configuration"
|
||||
sidebar_current: "docs-backends-config"
|
||||
description: |-
|
||||
Backends are configured directly in Terraform files in the `terraform` section.
|
||||
---
|
||||
|
||||
# Backend Configuration
|
||||
|
||||
Backends are configured directly in Terraform files in the `terraform`
|
||||
section. After configuring a backend, it has to be
|
||||
[initialized](/docs/backends/init.html).
|
||||
|
||||
Below, we show a complete example configuring the "consul" backend:
|
||||
|
||||
```hcl
|
||||
terraform {
|
||||
backend "consul" {
|
||||
address = "demo.consul.io"
|
||||
scheme = "https"
|
||||
path = "example_app/terraform_state"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You specify the backend type as a key to the `backend` stanza. Within the
|
||||
stanza are backend-specific configuration keys. The list of supported backends
|
||||
and their configuration details can be found [here](/docs/backends/types/index.html).
|
||||
|
||||
Only one backend may be specified and the configuration **may not contain
|
||||
interpolations**. Terraform will validate this.
|
||||
|
||||
## First Time Configuration
|
||||
|
||||
When configuring a backend for the first time (moving from no defined backend
|
||||
to explicitly configuring one), Terraform will give you the option to migrate
|
||||
your state to the new backend. This lets you adopt backends without losing
|
||||
any existing state.
|
||||
|
||||
To be extra careful, we always recommend manually backing up your state
|
||||
as well. You can do this by simply copying your `terraform.tfstate` file
|
||||
to another location. The initialization process should create a backup
|
||||
as well, but it never hurts to be safe!
|
||||
|
||||
Configuring a backend for the first time is no different than changing
|
||||
a configuration in the future: create the new configuration and run
|
||||
`terraform init`. Terraform will guide you the rest of the way.
|
||||
|
||||
## Partial Configuration
|
||||
|
||||
You do not need to specify every required argument in the backend configuration.
|
||||
Omitting certain arguments may be desirable to avoid storing secrets, such as
|
||||
access keys, within the main configuration. When some or all of the arguments
|
||||
are omitted, we call this a _partial configuration_.
|
||||
|
||||
With a partial configuration, the remaining configuration arguments must be
|
||||
provided as part of
|
||||
[the initialization process](/docs/backends/init.html#backend-initialization).
|
||||
There are several ways to supply the remaining arguments:
|
||||
|
||||
* **Interactively**: Terraform will interactively ask you for the required
|
||||
values, unless interactive input is disabled. Terraform will not prompt for
|
||||
optional values.
|
||||
|
||||
* **File**: A [backend configuration file](#backend-configuration-file) may be specified via the
|
||||
`init` command line. To specify a file, use the `-backend-config=PATH`
|
||||
option when running `terraform init`. If the file contains secrets it may be
|
||||
kept in a secure data store, such as [Vault](https://www.vaultproject.io/),
|
||||
in which case it must be downloaded to the local disk before running
|
||||
Terraform.
|
||||
|
||||
* **Command-line key/value pairs**: Key/value pairs can be specified via the
|
||||
`init` command line. Note that many shells retain command-line flags in a
|
||||
history file, so this isn't recommended for secrets. To specify a single
|
||||
key/value pair, use the `-backend-config="KEY=VALUE"` option when running
|
||||
`terraform init`.
|
||||
|
||||
If backend settings are provided in multiple locations, the top-level
|
||||
settings are merged such that any command-line options override the settings
|
||||
in the main configuration and then the command-line options are processed
|
||||
in order, with later options overriding values set by earlier options.
|
||||
|
||||
The final, merged configuration is stored on disk in the `.terraform`
|
||||
directory, which should be ignored from version control. This means that
|
||||
sensitive information can be omitted from version control, but it will be
|
||||
present in plain text on local disk when running Terraform.
|
||||
|
||||
When using partial configuration, Terraform requires at a minimum that
|
||||
an empty backend configuration is specified in one of the root Terraform
|
||||
configuration files, to specify the backend type. For example:
|
||||
|
||||
```hcl
|
||||
terraform {
|
||||
backend "consul" {}
|
||||
}
|
||||
```
|
||||
|
||||
## Backend Configuration File
|
||||
A backend configuration file has the contents of the `backend` block as
|
||||
top-level attributes, without the need to wrap it in another `terraform`
|
||||
or `backend` block:
|
||||
|
||||
```hcl
|
||||
address = "demo.consul.io"
|
||||
path = "example_app/terraform_state"
|
||||
scheme = "https"
|
||||
```
|
||||
|
||||
The same settings can alternatively be specified on the command line as
|
||||
follows:
|
||||
|
||||
```
|
||||
$ terraform init \
|
||||
-backend-config="address=demo.consul.io" \
|
||||
-backend-config="path=example_app/terraform_state" \
|
||||
-backend-config="scheme=https"
|
||||
```
|
||||
|
||||
## Changing Configuration
|
||||
|
||||
You can change your backend configuration at any time. You can change
|
||||
both the configuration itself as well as the type of backend (for example
|
||||
from "consul" to "s3").
|
||||
|
||||
Terraform will automatically detect any changes in your configuration
|
||||
and request a [reinitialization](/docs/backends/init.html). As part of
|
||||
the reinitialization process, Terraform will ask if you'd like to migrate
|
||||
your existing state to the new configuration. This allows you to easily
|
||||
switch from one backend to another.
|
||||
|
||||
If you're using multiple [workspaces](/docs/language/state/workspaces.html),
|
||||
Terraform can copy all workspaces to the destination. If Terraform detects
|
||||
you have multiple workspaces, it will ask if this is what you want to do.
|
||||
|
||||
If you're just reconfiguring the same backend, Terraform will still ask if you
|
||||
want to migrate your state. You can respond "no" in this scenario.
|
||||
|
||||
## Unconfiguring a Backend
|
||||
|
||||
If you no longer want to use any backend, you can simply remove the
|
||||
configuration from the file. Terraform will detect this like any other
|
||||
change and prompt you to [reinitialize](/docs/backends/init.html).
|
||||
|
||||
As part of the reinitialization, Terraform will ask if you'd like to migrate
|
||||
your state back down to normal local state. Once this is complete then
|
||||
Terraform is back to behaving as it does by default.
|
||||
@ -1,45 +0,0 @@
|
||||
---
|
||||
layout: "language"
|
||||
page_title: "Backends"
|
||||
sidebar_current: "docs-backends-index"
|
||||
description: |-
|
||||
A "backend" in Terraform determines how state is loaded and how an operation such as `apply` is executed. This abstraction enables non-local file state storage, remote execution, etc.
|
||||
---
|
||||
|
||||
# Backends
|
||||
|
||||
A "backend" in Terraform determines how state is loaded and how an operation
|
||||
such as `apply` is executed. This abstraction enables non-local file state
|
||||
storage, remote execution, etc.
|
||||
|
||||
By default, Terraform uses the "local" backend, which is the normal behavior
|
||||
of Terraform you're used to. This is the backend that was being invoked
|
||||
throughout the [introduction](/intro/index.html).
|
||||
|
||||
Here are some of the benefits of backends:
|
||||
|
||||
* **Working in a team**: Backends can store their state remotely and
|
||||
protect that state with locks to prevent corruption. Some backends
|
||||
such as Terraform Cloud even automatically store a history of
|
||||
all state revisions.
|
||||
|
||||
* **Keeping sensitive information off disk**: State is retrieved from
|
||||
backends on demand and only stored in memory. If you're using a backend
|
||||
such as Amazon S3, the only location the state ever is persisted is in
|
||||
S3.
|
||||
|
||||
* **Remote operations**: For larger infrastructures or certain changes,
|
||||
`terraform apply` can take a long, long time. Some backends support
|
||||
remote operations which enable the operation to execute remotely. You can
|
||||
then turn off your computer and your operation will still complete. Paired
|
||||
with remote state storage and locking above, this also helps in team
|
||||
environments.
|
||||
|
||||
**Backends are completely optional**. You can successfully use Terraform without
|
||||
ever having to learn or use backends. However, they do solve pain points that
|
||||
afflict teams at a certain scale. If you're an individual, you can likely
|
||||
get away with never using backends.
|
||||
|
||||
Even if you only intend to use the "local" backend, it may be useful to
|
||||
learn about backends since you can also change the behavior of the local
|
||||
backend.
|
||||
@ -1,31 +0,0 @@
|
||||
---
|
||||
layout: "language"
|
||||
page_title: "Backends: Init"
|
||||
sidebar_current: "docs-backends-init"
|
||||
description: |-
|
||||
Terraform must initialize any configured backend before use. This can be done by simply running `terraform init`.
|
||||
---
|
||||
|
||||
# Backend Initialization
|
||||
|
||||
Terraform must initialize any configured backend before use. This can be
|
||||
done by simply running `terraform init`.
|
||||
|
||||
The `terraform init` command should be run by any member of your team on
|
||||
any Terraform configuration as a first step. It is safe to execute multiple
|
||||
times and performs all the setup actions required for a Terraform environment,
|
||||
including initializing the backend.
|
||||
|
||||
The `init` command must be called:
|
||||
|
||||
* On any new environment that configures a backend
|
||||
* On any change of the backend configuration (including type of backend)
|
||||
* On removing backend configuration completely
|
||||
|
||||
You don't need to remember these exact cases. Terraform will detect when
|
||||
initialization is required and error in that situation. Terraform doesn't
|
||||
auto-initialize because it may require additional information from the user,
|
||||
perform state migrations, etc.
|
||||
|
||||
The `init` command will do more than just initialize the backend. Please see
|
||||
the [init documentation](/docs/commands/init.html) for more information.
|
||||
@ -1,25 +0,0 @@
|
||||
---
|
||||
layout: "language"
|
||||
page_title: "Backend: Supported Backend Types"
|
||||
sidebar_current: "docs-backends-types-index"
|
||||
description: |-
|
||||
Terraform can store the state remotely, making it easier to version and work with in a team.
|
||||
---
|
||||
|
||||
# Backend Types
|
||||
|
||||
This section documents the various backend types supported by Terraform.
|
||||
If you're not familiar with backends, please
|
||||
[read the sections about backends](/docs/backends/index.html) first.
|
||||
|
||||
Backends may support differing levels of features in Terraform. We differentiate
|
||||
these by calling a backend either **standard** or **enhanced**. All backends
|
||||
must implement **standard** functionality. These are defined below:
|
||||
|
||||
* **Standard**: State management, functionality covered in
|
||||
[State Storage & Locking](/docs/language/state/backends.html)
|
||||
|
||||
* **Enhanced**: Everything in standard plus
|
||||
[remote operations](/docs/backends/operations.html).
|
||||
|
||||
The backends are separated in the left by standard and enhanced.
|
||||
@ -1,22 +0,0 @@
|
||||
---
|
||||
layout: "language"
|
||||
page_title: "Provider: Terraform"
|
||||
sidebar_current: "docs-terraform-index"
|
||||
description: |-
|
||||
The special `terraform_remote_state` data source is used to access outputs from shared infrastructure.
|
||||
---
|
||||
|
||||
# The Built-In `terraform` Provider
|
||||
|
||||
Terraform includes one built-in data source:
|
||||
[`terraform_remote_state`](/docs/language/state/remote-state-data.html), which
|
||||
provides access to root module outputs from some other Terraform configuration.
|
||||
|
||||
This data source is implemented by a built-in provider, whose
|
||||
[source address](/docs/language/providers/requirements.html#source-addresses)
|
||||
is `terraform.io/builtin/terraform`. You do not need to require or configure
|
||||
this provider in order to use the `terraform_remote_state` data source; it is
|
||||
always available.
|
||||
|
||||
The `terraform_remote_state` data source is
|
||||
[documented in the Terraform Language docs](/docs/language/state/remote-state-data.html).
|
||||
@ -1,20 +0,0 @@
|
||||
---
|
||||
layout: "language"
|
||||
page_title: "State: Environments"
|
||||
sidebar_current: "docs-state-env"
|
||||
description: |-
|
||||
Legacy terminology for "Workspaces".
|
||||
---
|
||||
|
||||
# State Environments
|
||||
|
||||
The term _state environment_, or just _environment_, was used within the
|
||||
Terraform 0.9 releases to refer to the idea of having multiple distinct,
|
||||
named states associated with a single configuration directory.
|
||||
|
||||
After this concept was implemented, we received feedback that this terminology
|
||||
caused confusion due to other uses of the word "environment", both within
|
||||
Terraform itself and within organizations using Terraform.
|
||||
|
||||
As of 0.10, the preferred term is "workspace". For more information on
|
||||
workspaces, see [the main Workspaces page](/docs/language/state/workspaces.html).
|
||||
Loading…
Reference in new issue