website: revise docs for remote backend and credentials config
This commit is contained in:
parent
313108201d
commit
4612a71414
|
@ -10,64 +10,84 @@ description: |-
|
||||||
|
|
||||||
**Kind: Enhanced**
|
**Kind: Enhanced**
|
||||||
|
|
||||||
The remote backend stores state and runs operations remotely. In order
|
The remote backend stores state and runs operations remotely. When running
|
||||||
use this backend you need a Terraform Enterprise account or have Private
|
`terraform plan` with this backend, the actual execution occurs in Terraform
|
||||||
Terraform Enterprise running on-premises.
|
Enterprise, with log output streaming to the local terminal.
|
||||||
|
|
||||||
### Commands
|
To use this backend you need a Terraform Enterprise account on
|
||||||
|
[app.terraform.io](https://app.terraform.io) or a private instance of Terraform
|
||||||
|
Enterprise.
|
||||||
|
|
||||||
|
## Command Support
|
||||||
|
|
||||||
Currently the remote backend supports the following Terraform commands:
|
Currently the remote backend supports the following Terraform commands:
|
||||||
|
|
||||||
1. fmt
|
- `fmt`
|
||||||
2. get
|
- `get`
|
||||||
3. init
|
- `init`
|
||||||
4. output
|
- `output`
|
||||||
5. plan
|
- `plan`
|
||||||
6. providers
|
- `providers`
|
||||||
7. show
|
- `show`
|
||||||
8. taint
|
- `taint`
|
||||||
9. untaint
|
- `untaint`
|
||||||
10. validate
|
- `validate`
|
||||||
11. version
|
- `version`
|
||||||
11. workspace
|
- `workspace`
|
||||||
|
|
||||||
### Workspaces
|
Importantly, it does not support the `apply` command.
|
||||||
To work with remote workspaces we need either a name or a prefix. You will
|
|
||||||
get a configuration error when neither or both options are configured.
|
|
||||||
|
|
||||||
#### Name
|
## Workspaces
|
||||||
When a name is provided, that name is used to make a one-to-one mapping
|
|
||||||
between your local “default” workspace and a named remote workspace. This
|
|
||||||
option assumes you are not using workspaces when working with TF, so it
|
|
||||||
will act as a backend that does not support names states.
|
|
||||||
|
|
||||||
#### Prefix
|
The remote backend can work with either a single remote workspace, or with multiple similarly-named remote workspaces (like `networking-dev` and `networking-prod`). The `workspaces` block of the backend configuration determines which mode it uses:
|
||||||
When a prefix is provided it will be used to filter and map workspaces that
|
|
||||||
can be used with a single configuration. This allows you to dynamically
|
|
||||||
filter and map all remote workspaces with a matching prefix.
|
|
||||||
|
|
||||||
The prefix is added when making calls to the remote backend and stripped
|
- To use a single workspace, set `workspaces.name` to the remote workspace's
|
||||||
again when receiving the responses. This way any locally used workspace
|
full name (like `networking-prod`).
|
||||||
names will remain the same short names (e.g. “tst”, “acc”) while the remote
|
|
||||||
names will be mapped by adding the prefix.
|
|
||||||
|
|
||||||
It is assumed that you are only using named workspaces when working with
|
- To use multiple workspaces, set `workspaces.prefix` to a prefix used in
|
||||||
Terraform and so the “default” workspace is ignored in this case. If there
|
all of the desired remote workspace names. For example, set
|
||||||
is a state file for the “default” config, this will give an error during
|
`prefix = "networking-"` to use a group of workspaces with names like
|
||||||
`terraform init`. If the default workspace is selected when running the
|
`networking-dev` and `networking-prod`.
|
||||||
`init` command, the `init` process will succeed but will end with a message
|
|
||||||
that tells you how to select an existing workspace or create a new one.
|
When interacting with workspaces on the command line, Terraform uses
|
||||||
|
shortened names without the common prefix. For example, if
|
||||||
|
`prefix = "networking-"`, use `terraform workspace select prod` to switch to
|
||||||
|
the `networking-prod` workspace.
|
||||||
|
|
||||||
|
In prefix mode, the special `default` workspace is disabled. Before running
|
||||||
|
`terraform init`, ensure that there is no state stored for the local
|
||||||
|
`default` workspace and that a non-default workspace is currently selected;
|
||||||
|
otherwise, the initialization will fail.
|
||||||
|
|
||||||
|
The backend configuration requires either `name` or `prefix`. Omitting both or
|
||||||
|
setting both results in a configuration error.
|
||||||
|
|
||||||
|
If previous state is present when you run `terraform init` and the corresponding
|
||||||
|
remote workspaces are empty or absent, Terraform will create workspaces and/or
|
||||||
|
update the remote state accordingly.
|
||||||
|
|
||||||
## Example Configuration
|
## Example Configuration
|
||||||
|
|
||||||
```hcl
|
```hcl
|
||||||
|
# Using a single workspace:
|
||||||
|
terraform {
|
||||||
|
backend "remote" {
|
||||||
|
hostname = "app.terraform.io"
|
||||||
|
organization = "company"
|
||||||
|
|
||||||
|
workspaces {
|
||||||
|
name = "my-app-prod"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
# Using multiple workspaces:
|
||||||
terraform {
|
terraform {
|
||||||
backend "remote" {
|
backend "remote" {
|
||||||
hostname = "app.terraform.io"
|
hostname = "app.terraform.io"
|
||||||
organization = "company"
|
organization = "company"
|
||||||
|
|
||||||
workspaces {
|
workspaces {
|
||||||
name = "workspace"
|
|
||||||
prefix = "my-app-"
|
prefix = "my-app-"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
@ -84,7 +104,7 @@ data "terraform_remote_state" "foo" {
|
||||||
organization = "company"
|
organization = "company"
|
||||||
|
|
||||||
workspaces {
|
workspaces {
|
||||||
name = "workspace"
|
name = "my-app-prod"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
@ -99,16 +119,16 @@ The following configuration options are supported:
|
||||||
* `organization` - (Required) The name of the organization containing the
|
* `organization` - (Required) The name of the organization containing the
|
||||||
targeted workspace(s).
|
targeted workspace(s).
|
||||||
* `token` - (Optional) The token used to authenticate with the remote backend.
|
* `token` - (Optional) The token used to authenticate with the remote backend.
|
||||||
We recommend omitting the token which can be set as `credentials` in the
|
We recommend omitting the token from the configuration, and instead setting it
|
||||||
|
as `credentials` in the
|
||||||
[CLI config file](/docs/commands/cli-config.html#credentials).
|
[CLI config file](/docs/commands/cli-config.html#credentials).
|
||||||
* `workspaces` - (Required) Workspaces contains arguments used to filter down
|
* `workspaces` - (Required) A block specifying which remote workspace(s) to use.
|
||||||
to a set of workspaces to work on. Parameters defined below.
|
The `workspaces` block supports the following keys:
|
||||||
|
|
||||||
The `workspaces` block supports the following keys:
|
* `name` - (Optional) The full name of one remote workspace. When configured,
|
||||||
* `name` - (Optional) A workspace name used to map the default workspace to a
|
only the default workspace can be used. This option conflicts with `prefix`.
|
||||||
named remote workspace. When configured only the default workspace can be
|
* `prefix` - (Optional) A prefix used in the names of one or more remote
|
||||||
used. This option conflicts with `prefix`.
|
workspaces, all of which can be used with this configuration. The full
|
||||||
* `prefix` - (Optional) A prefix used to filter workspaces using a single
|
workspace names are used in Terraform Enterprise, and the short names
|
||||||
configuration. New workspaces will automatically be prefixed with this
|
(minus the prefix) are used on the command line. If omitted, only the
|
||||||
prefix. If omitted only the default workspace can be used. This option
|
default workspace can be used. This option conflicts with `name`.
|
||||||
conflicts with `name`.
|
|
||||||
|
|
|
@ -60,15 +60,16 @@ The following settings can be set in the CLI configuration file:
|
||||||
[plugin caching](/docs/configuration/providers.html#provider-plugin-cache)
|
[plugin caching](/docs/configuration/providers.html#provider-plugin-cache)
|
||||||
and specifies, as a string, the location of the plugin cache directory.
|
and specifies, as a string, the location of the plugin cache directory.
|
||||||
|
|
||||||
- `credentials` — provides credentials for use with Terraform Enterprise's
|
- `credentials` — provides credentials for use with Terraform Enterprise.
|
||||||
[private module registry.](/docs/enterprise/registry/index.html) This is
|
Terraform uses this when performing remote operations or state access with
|
||||||
only necessary when running Terraform on the command line; runs managed by
|
the [remote backend](../backends/types/remote.html) and when accessing
|
||||||
Terraform Enterprise can access private modules automatically.
|
Terraform Enterprise's [private module registry.](/docs/enterprise/registry/index.html)
|
||||||
|
|
||||||
This setting is a repeatable block, where the block label is a hostname
|
This setting is a repeatable block, where the block label is a hostname
|
||||||
(either `app.terraform.io` or the hostname of your private install) and
|
(either `app.terraform.io` or the hostname of your private install) and
|
||||||
the block body contains a `token` attribute. Whenever Terraform requests
|
the block body contains a `token` attribute. Whenever Terraform accesses
|
||||||
module data from that hostname, it will authenticate with that token.
|
state, modules, or remote operations from that hostname, it will
|
||||||
|
authenticate with that API token.
|
||||||
|
|
||||||
``` hcl
|
``` hcl
|
||||||
credentials "app.terraform.io" {
|
credentials "app.terraform.io" {
|
||||||
|
@ -76,11 +77,16 @@ The following settings can be set in the CLI configuration file:
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
~> **Note:** The credentials hostname must match the hostname in your module
|
~> **Important:** The token provided here must be a
|
||||||
sources. If your Terraform Enterprise instance is available at multiple
|
[user API token](/docs/enterprise/users-teams-organizations/users.html#api-tokens),
|
||||||
hostnames, use one of them consistently. (The SaaS version of Terraform
|
and not a team or organization token.
|
||||||
Enterprise responds to API calls at both its newer hostname,
|
|
||||||
app.terraform.io, and its historical hostname, atlas.hashicorp.com.)
|
-> **Note:** The credentials hostname must match the hostname in your module
|
||||||
|
sources and/or backend configuration. If your Terraform Enterprise instance
|
||||||
|
is available at multiple hostnames, use one of them consistently. (The SaaS
|
||||||
|
version of Terraform Enterprise responds to API calls at both its newer
|
||||||
|
hostname, app.terraform.io, and its historical hostname,
|
||||||
|
atlas.hashicorp.com.)
|
||||||
|
|
||||||
## Deprecated Settings
|
## Deprecated Settings
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue