website: Language: Remove several ghost pages, update links

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. 👻🚫
This commit is contained in:
Nick Fagerlund 2021-01-15 15:41:43 -08:00
parent 7a8dd326c6
commit 8cfcd82be3
26 changed files with 34 additions and 354 deletions

View File

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

View File

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

View File

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

View File

@ -1,32 +0,0 @@
---
layout: "language"
page_title: "Backends: Remote Operations (plan, apply, etc.)"
sidebar_current: "docs-backends-operations"
description: |-
Some backends support the ability to run operations (`refresh`, `plan`, `apply`, etc.) remotely. Terraform will continue to look and behave as if they're running locally while they in fact run on a remote machine.
---
# Remote Operations (plan, apply, etc.)
Most backends run all operations on the local system — although Terraform stores
its state remotely with these backends, it still executes its logic locally and
makes API requests directly from the system where it was invoked.
This is simple to understand and work with, but when many people are
collaborating on the same Terraform configurations, it requires everyone's
execution environment to be similar. This includes sharing access to
infrastructure provider credentials, keeping Terraform versions in sync,
keeping Terraform variables in sync, and installing any extra software required
by Terraform providers. This becomes more burdensome as teams get larger.
Some backends can run operations (`plan`, `apply`, etc.) on a remote machine,
while appearing to execute locally. This enables a more consistent execution
environment and more powerful access controls, without disrupting workflows
for users who are already comfortable with running Terraform.
Currently, [the `remote` backend](./types/remote.html) is the only backend to
support remote operations, and [Terraform Cloud](/docs/cloud/index.html)
is the only remote execution environment that supports it. For more information, see:
- [The `remote` backend](./types/remote.html)
- [Terraform Cloud's CLI-driven run workflow](/docs/cloud/run/cli.html)

View File

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

View File

@ -75,7 +75,7 @@ activating credentials) before running `terraform init`.
## Backend Initialization
During init, the root configuration directory is consulted for
[backend configuration](/docs/backends/config.html) and the chosen backend
[backend configuration](/docs/language/settings/backends/configuration.html) and the chosen backend
is initialized using the given configuration settings.
Re-running init with an already-initialized backend will update the working
@ -91,7 +91,7 @@ when the working directory was already previously initialized for a particular
backend.
The `-backend-config=...` option can be used for
[partial backend configuration](/docs/backends/config.html#partial-configuration),
[partial backend configuration](/docs/language/settings/backends/configuration.html#partial-configuration),
in situations where the backend settings are dynamic or sensitive and so cannot
be statically specified in the configuration file.

View File

@ -98,7 +98,7 @@ path of the root module. In general, you probably want the
The syntax is `terraform.<FIELD>`. This variable type contains metadata about
the currently executing Terraform run. FIELD can currently only be `env` to
reference the currently active [state environment](/docs/state/environments.html).
reference the currently active workspace.
## Conditionals

View File

@ -15,7 +15,7 @@ feature that was removed in Terraform 0.12.
The [`terraform push` command](/docs/commands/push.html) uploads a configuration to a Terraform Enterprise (legacy) environment. The name of the environment (and the organization it's in) can be specified on the command line, or as part of the Terraform configuration in an `atlas` block.
The `atlas` block does not configure remote state; it only configures the push command. For remote state, [use a `terraform { backend "<NAME>" {...} }` block](/docs/backends/config.html).
The `atlas` block does not configure remote state; it only configures the push command. For remote state, use a `terraform { backend "<NAME>" {...} }` block.
This page assumes you're familiar with the
[configuration syntax](./syntax.html)

View File

@ -41,7 +41,7 @@ that must be met to perform operations on this configuration. If the
running Terraform version doesn't meet these constraints, an error
is shown. See the section below dedicated to this option.
See [backends](/docs/backends/index.html) for more detail on the `backend`
See [backends](/docs/language/settings/backends/configuration.html) for more detail on the `backend`
configuration.
**No value within the `terraform` block can use interpolations.** The

View File

@ -111,9 +111,7 @@ To browse the publicly available providers and their documentation, see
-> **Note:** Provider documentation used to be hosted directly on terraform.io,
as part of Terraform's core documentation. Although some provider documentation
might still be hosted here, the Terraform Registry is now the main home for all
public provider docs. (The exception is the built-in
[`terraform` provider](/docs/providers/terraform/index.html) for reading state
data, since it is not available on the Terraform Registry.)
public provider docs.
## Resource Behavior

View File

@ -75,7 +75,7 @@ terraform {
}
```
-> **NOTE:** When using a Service Principal or an Access Key - we recommend using a [Partial Configuration](/docs/backends/config.html) for the credentials.
-> **NOTE:** When using a Service Principal or an Access Key - we recommend using a [Partial Configuration](/docs/language/settings/backends/configuration.html#partial-configuration) for the credentials.
## Data Source Configuration

View File

@ -41,7 +41,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 _[Backend Types](/docs/backends/types/index.html)_ for details about each supported backend type and its configuration arguments.
See the list of backend types in the navigation sidebar for details about each supported backend type and its configuration arguments.
### Default Backend
@ -71,7 +71,7 @@ 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).
[the initialization process](/docs/cli/init/index.html).
There are several ways to supply the remaining arguments:
* **File**: A configuration file may be specified via the `init` command line.
@ -145,7 +145,7 @@ 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
and request a [reinitialization](/docs/cli/init/index.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.
@ -161,7 +161,7 @@ want to migrate your state. You can respond "no" in this scenario.
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).
change and prompt you to [reinitialize](/docs/cli/init/index.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

View File

@ -27,7 +27,7 @@ terraform {
```
Note that for the access credentials we recommend using a
[partial configuration](/docs/backends/config.html).
[partial configuration](/docs/language/settings/backends/configuration.html#partial-configuration).
## Data Source Configuration

View File

@ -27,7 +27,7 @@ terraform {
```
Note that for the access credentials we recommend using a
[partial configuration](/docs/backends/config.html).
[partial configuration](/docs/language/settings/backends/configuration.html#partial-configuration).
## Data Source Configuration

View File

@ -33,7 +33,7 @@ If the `in_cluster_config` flag is set the backend will attempt to use a [servic
For most use cases either `in_cluster_config` or `load_config_file` will need to be set to `true`. If both flags are set the configuration from `load_config_file` will be used.
Note that for the access credentials we recommend using a [partial configuration](/docs/backends/config.html#partial-configuration).
Note that for the access credentials we recommend using a [partial configuration](/docs/language/settings/backends/configuration.html#partial-configuration).
## Example Referencing

View File

@ -24,7 +24,7 @@ terraform {
```
Note that for the access credentials we recommend using a
[partial configuration](/docs/backends/config.html).
[partial configuration](/docs/language/settings/backends/configuration.html#partial-configuration).
## Data Source Configuration

View File

@ -32,7 +32,9 @@ createdb terraform_backend
This `createdb` command is found in [Postgres client applications](https://www.postgresql.org/docs/9.5/reference-client.html) which are installed along with the database server.
We recommend using a [partial configuration](/docs/backends/config.html#partial-configuration) for the `conn_str` variable, because it typically contains access credentials that should not be committed to source control:
We recommend using a
[partial configuration](/docs/language/settings/backends/configuration.html#partial-configuration)
for the `conn_str` variable, because it typically contains access credentials that should not be committed to source control:
```hcl
terraform {

View File

@ -37,7 +37,7 @@ This assumes we have a bucket created called `mybucket`. The
Terraform state is written to the key `path/to/my/key`.
Note that for the access credentials we recommend using a
[partial configuration](/docs/backends/config.html).
[partial configuration](/docs/language/settings/backends/configuration.html#partial-configuration).
### S3 Bucket Permissions

View File

@ -27,7 +27,7 @@ terraform {
This will create a container called `terraform-state` and an object within that container called `tfstate.tf`. It will enable versioning using the `terraform-state-archive` container to contain the older version.
For the access credentials we recommend using a
[partial configuration](/docs/backends/config.html).
[partial configuration](/docs/language/settings/backends/configuration.html#partial-configuration).
## Data Source Configuration

View File

@ -65,9 +65,11 @@ prior to forcing the overwrite.
## State Locking
Backends are responsible for supporting [state locking](/docs/language/state/locking.html)
if possible. Not all backend types support state locking. In the
[list of supported backend types](/docs/backends/types/index.html) we explicitly note
whether locking is supported.
if possible.
Not all backends support locking. The
[documentation for each backend](/docs/language/settings/backends/index.html)
includes details on whether it supports locking or not.
For more information on state locking, view the
[page dedicated to state locking](/docs/language/state/locking.html).

View File

@ -8,7 +8,7 @@ description: |-
# State Locking
If supported by your [backend](/docs/backends/), Terraform will lock your
If supported by your [backend](/docs/language/settings/backends/index.html), Terraform will lock your
state for all operations that could write state. This prevents
others from acquiring the lock and potentially corrupting your state.
@ -21,9 +21,9 @@ If acquiring the lock is taking longer than expected, Terraform will output
a status message. If Terraform doesn't output a message, state locking is
still occurring if your backend supports it.
Not all [backends](/docs/backends/) support locking. Please view the list
of [backend types](/docs/backends/types/) for details on whether a backend
supports locking or not.
Not all backends support locking. The
[documentation for each backend](/docs/language/settings/backends/index.html)
includes details on whether it supports locking or not.
## Force Unlock

View File

@ -158,7 +158,7 @@ The following arguments are supported:
The `config` object can use any arguments that would be valid in the
equivalent `terraform { backend "<TYPE>" { ... } }` block. See
[the documentation of your chosen backend](/docs/backends/types/index.html)
[the documentation of your chosen backend](/docs/language/settings/backends/index.html)
for details.
-> **Note:** If the backend configuration requires a nested block, specify

View File

@ -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 a feature of [backends](/docs/backends/), which you can activate
in your configuration's root module.
Remote state is implemented by a [backend](/docs/language/settings/backends/index.html),
which you can configure in your configuration's root module.
## Delegation and Teamwork

View File

@ -8,7 +8,7 @@ description: |-
# Workspaces
Each Terraform configuration has an associated [backend](/docs/backends/index.html)
Each Terraform configuration has an associated [backend](/docs/language/settings/backends/index.html)
that defines how operations are executed and where persistent data such as
[the Terraform state](https://www.terraform.io/docs/language/state/purpose.html) are
stored.
@ -195,7 +195,7 @@ control, although using a remote backend instead is recommended when there are
multiple collaborators.
For [remote state](/docs/language/state/remote.html), the workspaces are stored
directly in the configured [backend](/docs/backends/). For example, if you
directly in the configured [backend](/docs/language/settings/backends/index.html). For example, if you
use [Consul](/docs/language/settings/backends/consul.html), the workspaces are stored
by appending the workspace name to the state path. To ensure that
workspace names are stored correctly and safely in all backends, the name

View File

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

View File

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