resilien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

website: revise docs for remote backend and credentials config

This commit is contained in:
Nick Fagerlund 2018-08-16 22:40:51 -07:00 committed by Martin Atkins
parent 313108201d
commit 4612a71414
2 changed files with 88 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

122
website/docs/backends/types/remote.html.md
View File

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

28
website/docs/commands/cli-config.html.markdown
View File

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