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**
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:
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`.

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