Merge pull request #4712 from TimeIncOSS/docs-remote-state-section
docs: Create new section for remote state backends
This commit is contained in:
James Nugent
commit
556dd16486
|
|
@ -35,6 +35,7 @@ body.layout-vsphere,
|
|||
body.layout-docs,
|
||||
body.layout-downloads,
|
||||
body.layout-inner,
|
||||
body.layout-remotestate,
|
||||
body.layout-terraform,
|
||||
body.layout-intro{
|
||||
background: $light-black image-url('sidebar-wire.png') left 62px no-repeat;
|
||||
|
|
|
|||
|
|
@ -40,70 +40,16 @@ below this section for more details.
|
|||
When remote storage is disabled, the existing remote state is migrated
|
||||
to a local file. This defaults to the `-state` path during restore.
|
||||
|
||||
The following backends are supported:
|
||||
|
||||
* Atlas - Stores the state in Atlas. Requires the `name` and `access_token`
|
||||
variables. The `address` variable can optionally be provided.
|
||||
|
||||
* Consul - Stores the state in the KV store at a given path. Requires the
|
||||
`path` variable. Supports the `CONSUL_HTTP_TOKEN` environment variable
|
||||
for specifying access credentials, or the `access_token` variable may
|
||||
be provided, but this is not recommended since it would be included in
|
||||
cleartext inside the persisted, shard state. Other supported parameters
|
||||
include:
|
||||
* `address` - DNS name and port of your Consul endpoint specified in the
|
||||
format `dnsname:port`. Defaults to the local agent HTTP listener. This
|
||||
may also be specified using the `CONSUL_HTTP_ADDR` environment variable.
|
||||
* `scheme` - Specifies what protocol to use when talking to the given
|
||||
`address`, either `http` or `https`. SSL support can also be triggered
|
||||
by setting then environment variable `CONSUL_HTTP_SSL` to `true`.
|
||||
* `http_auth` - HTTP Basic Authentication credentials to be used when
|
||||
communicating with Consul, in the format of either `user` or `user:pass`.
|
||||
This may also be specified using the `CONSUL_HTTP_AUTH` environment
|
||||
variable.
|
||||
|
||||
* Etcd - Stores the state in etcd at a given path.
|
||||
Requires the `path` and `endpoints` variables. The `username` and `password`
|
||||
variables can optionally be provided. `endpoints` is assumed to be a
|
||||
space-separated list of etcd endpoints.
|
||||
|
||||
* S3 - Stores the state as a given key in a given bucket on Amazon S3.
|
||||
Requires the `bucket` and `key` variables. Supports and honors the standard
|
||||
AWS environment variables `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`,
|
||||
`AWS_S3_ENDPOINT` and `AWS_DEFAULT_REGION`. These can optionally be provided
|
||||
as parameters in the `access_key`, `secret_key`, `endpoint` and `region`
|
||||
variables respectively, but passing credentials this way is not recommended
|
||||
since they will be included in cleartext inside the persisted state.
|
||||
Other supported parameters include:
|
||||
* `bucket` - the name of the S3 bucket
|
||||
* `key` - path where to place/look for state file inside the bucket
|
||||
* `encrypt` - whether to enable [server side encryption](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingServerSideEncryption.html)
|
||||
of the state file
|
||||
* `acl` - [Canned ACL](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl)
|
||||
to be applied to the state file.
|
||||
|
||||
* Artifactory - Stores the state as an artifact in a given repository in
|
||||
Artifactory. Requires the `url`, `username`, `password`, `repo` and `subpath`
|
||||
variables. Generic HTTP repositories are supported, and state from different
|
||||
configurations may be kept at different subpaths within the repository. The URL
|
||||
must include the path to the Artifactory installation - it will likely end in
|
||||
`/artifactory`. Alternately the following environment variables can be used in
|
||||
place of hard-coded values:
|
||||
* `ARTIFACTORY_USERNAME`
|
||||
* `ARTIFACTORY_PASSWORD`
|
||||
* `ARTIFACTORY_URL` (note that this is the base url to artifactory not the full repo and subpath)
|
||||
|
||||
|
||||
* HTTP - Stores the state using a simple REST client. State will be fetched
|
||||
via GET, updated via POST, and purged with DELETE. Requires the `address` variable.
|
||||
Supported storage backends and supported features of those
|
||||
are documented in the [Remote State](/docs/state/remote/index.html) section.
|
||||
|
||||
The command-line flags are all optional. The list of available flags are:
|
||||
|
||||
* `-backend=Atlas` - The remote backend to use. Must be one of the above
|
||||
* `-backend=Atlas` - The remote backend to use. Must be one of the
|
||||
supported backends.
|
||||
|
||||
* `-backend-config="k=v"` - Specify a configuration variable for a backend.
|
||||
This is how you set the required variables for the backends above.
|
||||
This is how you set the required variables for the backend.
|
||||
|
||||
* `-backup=path` - Path to backup the existing state file before
|
||||
modifying. Defaults to the "-state" path with ".backup" extension.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,54 @@
|
|||
---
|
||||
layout: "remotestate"
|
||||
page_title: "Remote State Backend: artifactory"
|
||||
sidebar_current: "docs-state-remote-artifactory"
|
||||
description: |-
|
||||
Terraform can store the state remotely, making it easier to version and work with in a team.
|
||||
---
|
||||
|
||||
# artifactory
|
||||
|
||||
Stores the state as an artifact in a given repository in [Artifactory](https://www.jfrog.com/artifactory/).
|
||||
|
||||
Generic HTTP repositories are supported, and state from different
|
||||
configurations may be kept at different subpaths within the repository.
|
||||
|
||||
-> **Note:** The URL must include the path to the Artifactory installation.
|
||||
It will likely end in `/artifactory`.
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
terraform remote config \
|
||||
-backend=artifactory \
|
||||
-backend-config="username=SheldonCooper" \
|
||||
-backend-config="password=AmyFarrahFowler" \
|
||||
-backend-config="url=https://custom.artifactoryonline.com/artifactory" \
|
||||
-backend-config="repo=foo" \
|
||||
-backend-config="subpath=terraform-bar"
|
||||
```
|
||||
|
||||
## Example Referencing
|
||||
|
||||
```
|
||||
resource "terraform_remote_state" "foo" {
|
||||
backend = "artifactory"
|
||||
config {
|
||||
username = "SheldonCooper"
|
||||
password = "AmyFarrahFowler"
|
||||
url = "https://custom.artifactoryonline.com/artifactory"
|
||||
repo = "foo"
|
||||
subpath = "terraform-bar"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration variables
|
||||
|
||||
The following configuration options / environment variables are supported:
|
||||
|
||||
* `username` / `ARTIFACTORY_USERNAME` (Required) - The username
|
||||
* `password` / `ARTIFACTORY_PASSWORD` (Required) - The password
|
||||
* `url` / `ARTIFACTORY_URL` (Required) - The URL. Note that this is the base url to artifactory not the full repo and subpath.
|
||||
* `repo` (Required) - The repository name
|
||||
* `subpath` (Required) - Path within the repository
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
---
|
||||
layout: "remotestate"
|
||||
page_title: "Remote State Backend: atlas"
|
||||
sidebar_current: "docs-state-remote-atlas"
|
||||
description: |-
|
||||
Terraform can store the state remotely, making it easier to version and work with in a team.
|
||||
---
|
||||
|
||||
# atlas
|
||||
|
||||
Stores the state in [Atlas](https://atlas.hashicorp.com/).
|
||||
|
||||
You can create a new environment in the [Environments section](https://atlas.hashicorp.com/environments)
|
||||
and generate new token in the [Tokens page](https://atlas.hashicorp.com/settings/tokens) under Settings.
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
terraform remote config \
|
||||
-backend=atlas \
|
||||
-backend-config="name=bigbang/example" \
|
||||
-backend-config="access_token=X2iTFefU5aWOjg.atlasv1.YaDa" \
|
||||
```
|
||||
|
||||
## Example Referencing
|
||||
|
||||
```
|
||||
resource "terraform_remote_state" "foo" {
|
||||
backend = "atlas"
|
||||
config {
|
||||
name = "bigbang/example"
|
||||
access_token = "X2iTFefU5aWOjg.atlasv1.YaDa"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration variables
|
||||
|
||||
The following configuration options / environment variables are supported:
|
||||
|
||||
* `name` - (Required) Full name of the environment (`<username>/<name>`)
|
||||
* `access_token` / `ATLAS_TOKEN` - (Required) Atlas API token
|
||||
* `address` - (Optional) Address to alternative Atlas location (Atlas Enterprise endpoint)
|
||||
|
|
@ -0,0 +1,48 @@
|
|||
---
|
||||
layout: "remotestate"
|
||||
page_title: "Remote State Backend: consul"
|
||||
sidebar_current: "docs-state-remote-consul"
|
||||
description: |-
|
||||
Terraform can store the state remotely, making it easier to version and work with in a team.
|
||||
---
|
||||
|
||||
# consul
|
||||
|
||||
Stores the state in the [Consul](https://www.consul.io/) KV store at a given path.
|
||||
|
||||
-> **Note:** Specifying `access_token` directly makes it included in
|
||||
cleartext inside the persisted, shard state.
|
||||
Use of the environment variable `CONSUL_HTTP_TOKEN` is recommended.
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
terraform remote config \
|
||||
-backend=consul \
|
||||
-backend-config="path=full/path"
|
||||
```
|
||||
|
||||
## Example Referencing
|
||||
|
||||
```
|
||||
resource "terraform_remote_state" "foo" {
|
||||
backend = "consul"
|
||||
config {
|
||||
path = "full/path"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration variables
|
||||
|
||||
The following configuration options / environment variables are supported:
|
||||
|
||||
* `path` - (Required) Path in the Consul KV store
|
||||
* `access_token` / `CONSUL_HTTP_TOKEN` - (Required) Access token
|
||||
* `address` / `CONSUL_HTTP_ADDR` - (Optional) DNS name and port of your Consul endpoint specified in the
|
||||
format `dnsname:port`. Defaults to the local agent HTTP listener.
|
||||
* `scheme` - (Optional) Specifies what protocol to use when talking to the given
|
||||
`address`, either `http` or `https`. SSL support can also be triggered
|
||||
by setting then environment variable `CONSUL_HTTP_SSL` to `true`.
|
||||
* `http_auth` / `CONSUL_HTTP_AUTH` - (Optional) HTTP Basic Authentication credentials to be used when
|
||||
communicating with Consul, in the format of either `user` or `user:pass`.
|
||||
|
|
@ -0,0 +1,41 @@
|
|||
---
|
||||
layout: "remotestate"
|
||||
page_title: "Remote State Backend: etcd"
|
||||
sidebar_current: "docs-state-remote-etcd"
|
||||
description: |-
|
||||
Terraform can store the state remotely, making it easier to version and work with in a team.
|
||||
---
|
||||
|
||||
# etcd
|
||||
|
||||
Stores the state in [etcd](https://coreos.com/etcd/) at a given path.
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
terraform remote config \
|
||||
-backend=etcd \
|
||||
-backend-config="path=path/to/terraform.tfstate" \
|
||||
-backend-config="endpoints=http://one:4001 http://two:4001"
|
||||
```
|
||||
|
||||
## Example Referencing
|
||||
|
||||
```
|
||||
resource "terraform_remote_state" "foo" {
|
||||
backend = "etcd"
|
||||
config {
|
||||
path = "path/to/terraform.tfstate"
|
||||
endpoints = "http://one:4001 http://two:4001"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration variables
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
* `path` - (Required) The path where to store the state
|
||||
* `endpoints` - (Required) A space-separated list of the etcd endpoints
|
||||
* `username` - (Optional) The username
|
||||
* `password` - (Optional) The password
|
||||
|
|
@ -0,0 +1,40 @@
|
|||
---
|
||||
layout: "remotestate"
|
||||
page_title: "Remote State Backend: http"
|
||||
sidebar_current: "docs-state-remote-http"
|
||||
description: |-
|
||||
Terraform can store the state remotely, making it easier to version and work with in a team.
|
||||
---
|
||||
|
||||
# http
|
||||
|
||||
Stores the state using a simple [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) client.
|
||||
|
||||
State will be fetched via GET, updated via POST, and purged with DELETE.
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
terraform remote config \
|
||||
-backend=http \
|
||||
-backend-config="address=http://my.rest.api.com"
|
||||
```
|
||||
|
||||
## Example Referencing
|
||||
|
||||
```
|
||||
resource "terraform_remote_state" "foo" {
|
||||
backend = "http"
|
||||
config {
|
||||
address = "http://my.rest.api.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration variables
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
* `address` - (Required) The address of the REST endpoint
|
||||
* `skip_cert_verification` - (Optional) Whether to skip TLS verification.
|
||||
Defaults to `false`.
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
layout: "remotestate"
|
||||
page_title: "Remote State"
|
||||
sidebar_current: "docs-state-remote"
|
||||
sidebar_current: "docs-state-remote_index"
|
||||
description: |-
|
||||
Terraform can store the state remotely, making it easier to version and work with in a team.
|
||||
---
|
||||
|
|
@ -0,0 +1,53 @@
|
|||
---
|
||||
layout: "remotestate"
|
||||
page_title: "Remote State Backend: s3"
|
||||
sidebar_current: "docs-state-remote-s3"
|
||||
description: |-
|
||||
Terraform can store the state remotely, making it easier to version and work with in a team.
|
||||
---
|
||||
|
||||
# s3
|
||||
|
||||
Stores the state as a given key in a given bucket on [Amazon S3](https://aws.amazon.com/s3/).
|
||||
|
||||
-> **Note:** Passing credentials directly via config options will
|
||||
make them included in cleartext inside the persisted state.
|
||||
Use of environment variables or config file is recommended.
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
terraform remote config \
|
||||
-backend=s3 \
|
||||
-backend-config="bucket=terraform-state-prod" \
|
||||
-backend-config="key=network/terraform.tfstate" \
|
||||
-backend-config="region=us-east-1"
|
||||
```
|
||||
|
||||
## Example Referencing
|
||||
|
||||
```
|
||||
resource "terraform_remote_state" "foo" {
|
||||
backend = "s3"
|
||||
config {
|
||||
bucket = "terraform-state-prod"
|
||||
key = "network/terraform.tfstate"
|
||||
region = "us-east-1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration variables
|
||||
|
||||
The following configuration options / environment variables are supported:
|
||||
|
||||
* `bucket` - (Required) The name of the S3 bucket
|
||||
* `key` - (Required) The path where to place/look for state file inside the bucket
|
||||
* `region` / `AWS_DEFAULT_REGION` - (Optional) The region of the S3 bucket
|
||||
* `endpoint` / `AWS_S3_ENDPOINT` - (Optional) A custom endpoint for the S3 API
|
||||
* `encrypt` - (Optional) Whether to enable [server side encryption](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingServerSideEncryption.html)
|
||||
of the state file
|
||||
* `acl` - [Canned ACL](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl)
|
||||
to be applied to the state file.
|
||||
* `access_key` / `AWS_ACCESS_KEY_ID` - (Optional) AWS access key
|
||||
* `secret_key` / `AWS_SECRET_ACCESS_KEY` - (Optional) AWS secret key
|
||||
|
|
@ -0,0 +1,44 @@
|
|||
---
|
||||
layout: "remotestate"
|
||||
page_title: "Remote State Backend: swift"
|
||||
sidebar_current: "docs-state-remote-swift"
|
||||
description: |-
|
||||
Terraform can store the state remotely, making it easier to version and work with in a team.
|
||||
---
|
||||
|
||||
# swift
|
||||
|
||||
Stores the state as an artifact in [Swift](http://docs.openstack.org/developer/swift/).
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
terraform remote config \
|
||||
-backend=swift \
|
||||
-backend-config="path=random/path"
|
||||
```
|
||||
|
||||
## Example Referencing
|
||||
|
||||
```
|
||||
resource "terraform_remote_state" "foo" {
|
||||
backend = "swift"
|
||||
config {
|
||||
path = "random/path"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration variables
|
||||
|
||||
The following configuration option is supported:
|
||||
|
||||
* `path` - (Required) The path where to store `terraform.tfstate`
|
||||
|
||||
The following environment variables are supported:
|
||||
|
||||
* `OS_AUTH_URL` - (Required) The identity endpoint
|
||||
* `OS_USERNAME` - (Required) The username
|
||||
* `OS_PASSWORD` - (Required) The password
|
||||
* `OS_REGION_NAME` - (Required) The region
|
||||
* `OS_TENANT_NAME` - (Required) The name of the tenant
|
||||
|
|
@ -113,7 +113,7 @@
|
|||
<a href="/docs/state/index.html">State</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-state-remote") %>>
|
||||
<a href="/docs/state/remote.html">Remote State</a>
|
||||
<a href="/docs/state/remote/index.html">Remote State</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,44 @@
|
|||
<% wrap_layout :inner do %>
|
||||
<% content_for :sidebar do %>
|
||||
<div class="docs-sidebar hidden-print affix-top" role="complementary">
|
||||
<ul class="nav docs-sidenav">
|
||||
<li<%= sidebar_current("docs-state") %>>
|
||||
<a href="/docs/state/index.html">« Documentation Home</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-state-remote_index") %>>
|
||||
<a href="/docs/state/remote/index.html">Remote State</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current(/^docs-state-remote-/) %>>
|
||||
<a href="#">Backends</a>
|
||||
<ul class="nav nav-visible">
|
||||
<li<%= sidebar_current("docs-state-remote-artifactory") %>>
|
||||
<a href="/docs/state/remote/artifactory.html">artifactory</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-state-remote-atlas") %>>
|
||||
<a href="/docs/state/remote/atlas.html">atlas</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-state-remote-consul") %>>
|
||||
<a href="/docs/state/remote/consul.html">consul</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-state-remote-etcd") %>>
|
||||
<a href="/docs/state/remote/etcd.html">etcd</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-state-remote-http") %>>
|
||||
<a href="/docs/state/remote/http.html">http</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-state-remote-s3") %>>
|
||||
<a href="/docs/state/remote/s3.html">s3</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-state-remote-swift") %>>
|
||||
<a href="/docs/state/remote/swift.html">swift</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<% end %>
|
||||
|
||||
<%= yield %>
|
||||
<% end %>
|
||||
Loading…
Reference in New Issue