website: revise docs for remote backend and credentials config
This commit is contained in:
Nick Fagerlund
Martin Atkins
parent
313108201d
commit
4612a71414
|
|
@ -10,64 +10,84 @@ description: |-
|
|||
|
||||
**Kind: Enhanced**
|
||||
|
||||
The remote backend stores state and runs operations remotely. In order
|
||||
use this backend you need a Terraform Enterprise account or have Private
|
||||
Terraform Enterprise running on-premises.
|
||||
The remote backend stores state and runs operations remotely. When running
|
||||
`terraform plan` with this backend, the actual execution occurs in Terraform
|
||||
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:
|
||||
|
||||
1. fmt
|
||||
2. get
|
||||
3. init
|
||||
4. output
|
||||
5. plan
|
||||
6. providers
|
||||
7. show
|
||||
8. taint
|
||||
9. untaint
|
||||
10. validate
|
||||
11. version
|
||||
11. workspace
|
||||
- `fmt`
|
||||
- `get`
|
||||
- `init`
|
||||
- `output`
|
||||
- `plan`
|
||||
- `providers`
|
||||
- `show`
|
||||
- `taint`
|
||||
- `untaint`
|
||||
- `validate`
|
||||
- `version`
|
||||
- `workspace`
|
||||
|
||||
### Workspaces
|
||||
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.
|
||||
Importantly, it does not support the `apply` command.
|
||||
|
||||
#### Name
|
||||
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.
|
||||
## Workspaces
|
||||
|
||||
#### Prefix
|
||||
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 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:
|
||||
|
||||
The prefix is added when making calls to the remote backend and stripped
|
||||
again when receiving the responses. This way any locally used workspace
|
||||
names will remain the same short names (e.g. “tst”, “acc”) while the remote
|
||||
names will be mapped by adding the prefix.
|
||||
- To use a single workspace, set `workspaces.name` to the remote workspace's
|
||||
full name (like `networking-prod`).
|
||||
|
||||
It is assumed that you are only using named workspaces when working with
|
||||
Terraform and so the “default” workspace is ignored in this case. If there
|
||||
is a state file for the “default” config, this will give an error during
|
||||
`terraform init`. If the default workspace is selected when running the
|
||||
`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.
|
||||
- To use multiple workspaces, set `workspaces.prefix` to a prefix used in
|
||||
all of the desired remote workspace names. For example, set
|
||||
`prefix = "networking-"` to use a group of workspaces with names like
|
||||
`networking-dev` and `networking-prod`.
|
||||
|
||||
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
|
||||
|
||||
```hcl
|
||||
# Using a single workspace:
|
||||
terraform {
|
||||
backend "remote" {
|
||||
hostname = "app.terraform.io"
|
||||
organization = "company"
|
||||
|
||||
workspaces {
|
||||
name = "my-app-prod"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Using multiple workspaces:
|
||||
terraform {
|
||||
backend "remote" {
|
||||
hostname = "app.terraform.io"
|
||||
organization = "company"
|
||||
|
||||
workspaces {
|
||||
name = "workspace"
|
||||
prefix = "my-app-"
|
||||
}
|
||||
}
|
||||
|
|
@ -84,7 +104,7 @@ data "terraform_remote_state" "foo" {
|
|||
organization = "company"
|
||||
|
||||
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
|
||||
targeted workspace(s).
|
||||
* `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).
|
||||
* `workspaces` - (Required) Workspaces contains arguments used to filter down
|
||||
to a set of workspaces to work on. Parameters defined below.
|
||||
|
||||
* `workspaces` - (Required) A block specifying which remote workspace(s) to use.
|
||||
The `workspaces` block supports the following keys:
|
||||
* `name` - (Optional) A workspace name used to map the default workspace to a
|
||||
named remote workspace. When configured only the default workspace can be
|
||||
used. This option conflicts with `prefix`.
|
||||
* `prefix` - (Optional) A prefix used to filter workspaces using a single
|
||||
configuration. New workspaces will automatically be prefixed with this
|
||||
prefix. If omitted only the default workspace can be used. This option
|
||||
conflicts with `name`.
|
||||
|
||||
* `name` - (Optional) The full name of one remote workspace. When configured,
|
||||
only the default workspace can be used. This option conflicts with `prefix`.
|
||||
* `prefix` - (Optional) A prefix used in the names of one or more remote
|
||||
workspaces, all of which can be used with this configuration. The full
|
||||
workspace names are used in Terraform Enterprise, and the short names
|
||||
(minus the prefix) are used on the command line. If omitted, only the
|
||||
default workspace can be used. This option 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)
|
||||
and specifies, as a string, the location of the plugin cache directory.
|
||||
|
||||
- `credentials` — provides credentials for use with Terraform Enterprise's
|
||||
[private module registry.](/docs/enterprise/registry/index.html) This is
|
||||
only necessary when running Terraform on the command line; runs managed by
|
||||
Terraform Enterprise can access private modules automatically.
|
||||
- `credentials` — provides credentials for use with Terraform Enterprise.
|
||||
Terraform uses this when performing remote operations or state access with
|
||||
the [remote backend](../backends/types/remote.html) and when accessing
|
||||
Terraform Enterprise's [private module registry.](/docs/enterprise/registry/index.html)
|
||||
|
||||
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
|
||||
the block body contains a `token` attribute. Whenever Terraform requests
|
||||
module data from that hostname, it will authenticate with that token.
|
||||
the block body contains a `token` attribute. Whenever Terraform accesses
|
||||
state, modules, or remote operations from that hostname, it will
|
||||
authenticate with that API token.
|
||||
|
||||
``` hcl
|
||||
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
|
||||
sources. 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.)
|
||||
~> **Important:** The token provided here must be a
|
||||
[user API token](/docs/enterprise/users-teams-organizations/users.html#api-tokens),
|
||||
and not a team or organization token.
|
||||
|
||||
-> **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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue