website: document backend types

This commit is contained in:
Mitchell Hashimoto 2017-02-15 12:19:38 -08:00
parent a240a9cac7
commit 03dca34161
No known key found for this signature in database
GPG Key ID: 744E147AA52F5B0A
12 changed files with 176 additions and 134 deletions

View File

@ -1,16 +1,17 @@
---
layout: "backend-types"
page_title: "Remote State Backend: artifactory"
page_title: "Backend Type: artifactory"
sidebar_current: "docs-backends-types-standard-artifactory"
description: |-
Terraform can store the state remotely, making it easier to version and work with in a team.
Terraform can store state in artifactory.
---
# artifactory
**Kind: Standard (with no locking)**
Stores the state as an artifact in a given repository in [Artifactory](https://www.jfrog.com/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.
@ -18,16 +19,18 @@ 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
## Example Configuration
```
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"
terraform {
backend "artifactory" {
username = "SheldonCooper"
password = "AmyFarrahFowler"
url = "https://custom.artifactoryonline.com/artifactory"
repo = "foo"
subpath = "teraraform-bar"
}
}
```
## Example Referencing

View File

@ -1,27 +1,36 @@
---
layout: "remotestate"
page_title: "Remote State Backend: atlas"
sidebar_current: "docs-state-remote-atlas"
layout: "backend-types"
page_title: "Backend Type: atlas"
sidebar_current: "docs-backends-types-standard-atlas"
description: |-
Terraform can store the state remotely, making it easier to version and work with in a team.
Terraform can store the state in Atlas.
---
# atlas
**Kind: Standard (with no locking)**
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.
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
## Example Configuration
```
terraform remote config \
-backend=atlas \
-backend-config="name=bigbang/example" \
-backend-config="access_token=X2iTFefU5aWOjg.atlasv1.YaDa" \
terraform {
backend "atlas" {
name = "bigbang/example"
access_token = "foo"
}
}
```
Note that for the access token we recommend using a
[partial configuration](/docs/backends/config.html).
## Example Referencing
```

View File

@ -1,30 +1,31 @@
---
layout: "remotestate"
page_title: "Remote State Backend: azure"
sidebar_current: "docs-state-remote-azure"
layout: "backend-types"
page_title: "Backend Type: azure"
sidebar_current: "docs-backends-types-standard-azure"
description: |-
Terraform can store the state remotely, making it easier to version and work with in a team.
Terraform can store state remotely in Azure Storage.
---
# azure
**Kind: Standard (with no locking)**
Stores the state as a given key in a given bucket on [Microsoft Azure Storage](https://azure.microsoft.com/en-us/documentation/articles/storage-introduction/).
-> **Note:** Passing credentials directly via config options will
make them included in cleartext inside the persisted state.
Access key should, ideally, be passed using the environment variable
`ARM_ACCESS_KEY` to follow this convention.
## Example Usage
## Example Configuration
```hcl
terraform {
backend "azure" {
storage_account_name = "abcd1234"
container_name = "tfstate"
key = "prod.terraform.tfstate"
}
}
```
terraform remote config \
-backend=azure \
-backend-config="storage_account_name=terraform123abc" \
-backend-config="container_name=terraform-state" \
-backend-config="key=prod.terraform.tfstate"
```
Note that for the access credentials we recommend using a
[partial configuration](/docs/backends/config.html).
## Example Referencing

View File

@ -1,27 +1,33 @@
---
layout: "remotestate"
page_title: "Remote State Backend: consul"
sidebar_current: "docs-state-remote-consul"
layout: "backend-types"
page_title: "Backend Type: consul"
sidebar_current: "docs-backends-types-standard-consul"
description: |-
Terraform can store the state remotely, making it easier to version and work with in a team.
Terraform can store state in Consul.
---
# consul
**Kind: Standard (with locking)**
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.
This backend supports [state locking](/docs/state/locking.html).
## Example Usage
## Example Configuration
```
terraform remote config \
-backend=consul \
-backend-config="path=full/path"
terraform {
backend "consul" {
address = "demo.consul.io"
path = "full/path"
}
}
```
Note that for the access credentials we recommend using a
[partial configuration](/docs/backends/config.html).
## Example Referencing
```

View File

@ -1,22 +1,26 @@
---
layout: "remotestate"
page_title: "Remote State Backend: etcd"
sidebar_current: "docs-state-remote-etcd"
layout: "backend-types"
page_title: "Backend Type: etcd"
sidebar_current: "docs-backends-types-standard-etcd"
description: |-
Terraform can store the state remotely, making it easier to version and work with in a team.
Terraform can store state remotely in etcd.
---
# etcd
**Kind: Standard (with no locking)**
Stores the state in [etcd](https://coreos.com/etcd/) at a given path.
## Example Usage
## Example Configuration
```
terraform remote config \
-backend=etcd \
-backend-config="path=path/to/terraform.tfstate" \
-backend-config="endpoints=http://one:4001 http://two:4001"
terraform {
backend "etcd" {
path = "path/to/terraform.tfstate"
endpoints = "http://one:4001 http://two:4001"
}
}
```
## Example Referencing

View File

@ -1,27 +1,27 @@
---
layout: "remotestate"
page_title: "Remote State Backend: gcs"
sidebar_current: "docs-state-remote-gcs"
layout: "backend-types"
page_title: "Backend Type: gcs"
sidebar_current: "docs-backends-types-standard-gcs"
description: |-
Terraform can store the state remotely, making it easier to version and work with in a team.
---
# gcs
**Kind: Standard (with no locking)**
Stores the state as a given key in a given bucket on [Google Cloud Storage](https://cloud.google.com/storage/).
-> **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
## Example Configuration
```
terraform remote config \
-backend=gcs \
-backend-config="bucket=terraform-state-prod" \
-backend-config="path=network/terraform.tfstate" \
-backend-config="project=goopro"
terraform {
backend "gcs" {
bucket = "tf-state-prod"
path = "path/terraform.tfstate"
project = "myproject"
}
}
```
## Example Referencing

View File

@ -1,13 +1,15 @@
---
layout: "remotestate"
page_title: "Remote State Backend: http"
sidebar_current: "docs-state-remote-http"
layout: "backend-types"
page_title: "Backend Type: http"
sidebar_current: "docs-backends-types-standard-http"
description: |-
Terraform can store the state remotely, making it easier to version and work with in a team.
Terraform can store state remotely at any valid HTTP endpoint.
---
# http
**Kind: Standard (with no locking)**
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.
@ -15,9 +17,11 @@ 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"
terraform {
backend "http" {
address = "http://myrest.api.com"
}
}
```
## Example Referencing

View File

@ -1,21 +1,26 @@
---
layout: "remotestate"
page_title: "Remote State Backend: local"
sidebar_current: "docs-state-remote-local"
layout: "backend-types"
page_title: "Backend Type: local"
sidebar_current: "docs-backends-types-enhanced-local"
description: |-
Remote state stored using the local file system.
Terraform can store the state remotely, making it easier to version and work with in a team.
---
# local
Remote state backend that uses the local file system.
**Kind: Enhanced**
## Example Usage
The local backend stores state on the local filesystem, locks that
state using system APIs, and performs operations locally.
## Example Configuration
```
terraform remote config \
-backend=local \
-backend-config="path=/path/to/terraform.tfstate"
terraform {
backend "local" {
path = "relative/path/to/terraform.tfstate"
}
}
```
## Example Reference
@ -23,6 +28,7 @@ terraform remote config \
```
data "terraform_remote_state" "foo" {
backend = "local"
config {
path = "${path.module}/../../terraform.tfstate"
}
@ -33,4 +39,5 @@ data "terraform_remote_state" "foo" {
The following configuration options are supported:
* `path` - (Required) The path to the `tfstate` file.
* `path` - (Optional) The path to the `tfstate` file. This defaults to
"terraform.tfstate" relative to the root module by default.

View File

@ -1,24 +1,31 @@
---
layout: "remotestate"
page_title: "Remote State Backend: manta"
sidebar_current: "docs-state-remote-manta"
layout: "backend-types"
page_title: "Backend Type: manta"
sidebar_current: "docs-backends-types-standard-manta"
description: |-
Terraform can store the state remotely, making it easier to version and work with in a team.
Terraform can store state in manta.
---
# manta
**Kind: Standard (with no locking)**
Stores the state as an artifact in [Manta](https://www.joyent.com/manta).
## Example Usage
## Example Configuration
```
terraform remote config \
-backend=manta \
-backend-config="path=random/path" \
-backend-config="objecName=terraform.tfstate"
terraform {
backend "manta" {
path = "random/path"
objectName = "terraform.tfstate"
}
}
```
Note that for the access credentials we recommend using a
[partial configuration](/docs/backends/config.html).
## Example Referencing
```

View File

@ -1,40 +1,41 @@
---
layout: "remotestate"
page_title: "Remote State Backend: s3"
sidebar_current: "docs-state-remote-s3"
layout: "backend-types"
page_title: "Backend Type: s3"
sidebar_current: "docs-backends-types-standard-s3"
description: |-
Terraform can store the state remotely, making it easier to version and work with in a team.
Terraform can store state remotely in S3 and lock that state with DynamoDB.
---
# S3
Stores the state as a given key in a given bucket on [Amazon
S3](https://aws.amazon.com/s3/).
**Kind: Standard (with locking via DynamoDB)**
Stores the state as a given key in a given bucket on
[Amazon S3](https://aws.amazon.com/s3/).
This backend also supports state locking via
[Dynamo DB](https://aws.amazon.com/dynamodb/).
~> **Warning!** It is highly recommended that you enable
[Bucket Versioning](http://docs.aws.amazon.com/AmazonS3/latest/UG/enable-bucket-versioning.html)
on the S3 bucket to allow for state recovery in the case of accidental deletions and human error.
## Using S3 for Remote State
To enable remote state on S3 we run the `terraform remote config`
command like so:
## Example Configuration
```
terraform remote config \
-backend=s3 \
-backend-config="bucket=terraform-state-prod" \
-backend-config="key=network/terraform.tfstate" \
-backend-config="region=us-east-1"
terraform {
backend "s3" {
bucket = "mybucket"
key = "path/to/my/key"
region = "us-east-1"
}
}
```
This assumes we have a bucket created called `terraform-state-prod`. The
Terraform state is written to the file `terraform.tfstate` in a folder
called `network`.
This assumes we have a bucket created called `mybucket`. The
Terraform state is written to the key `path/to/my/key`.
-> **Note:** Passing credentials directly via configuration options will
make them included in cleartext inside the persisted state. Use of
environment variables or a configuration file is recommended.
Note that for the access credentials we recommend using a
[partial configuration](/docs/backends/config.html).
## Using the S3 remote state

View File

@ -1,27 +1,30 @@
---
layout: "remotestate"
page_title: "Remote State Backend: swift"
sidebar_current: "docs-state-remote-swift"
layout: "backend-types"
page_title: "Backend Type: swift"
sidebar_current: "docs-backends-types-standard-swift"
description: |-
Terraform can store the state remotely, making it easier to version and work with in a team.
Terraform can store state remotely in Swift.
---
# swift
**Kind: Standard (with no locking)**
Stores the state as an artifact in [Swift](http://docs.openstack.org/developer/swift/).
-> **Note:** Passing credentials directly via configuration options will
make them included in cleartext inside the persisted state. Use of
environment variables is recommended.
## Example Usage
## Example Configuration
```
terraform remote config \
-backend=swift \
-backend-config="path=terraform_state"
terraform {
backend "swift" {
path = "terraform-state"
}
}
```
Note that for the access credentials we recommend using a
[partial configuration](/docs/backends/config.html).
## Example Referencing
```

View File

@ -43,9 +43,6 @@
<li<%= sidebar_current("docs-backends-types-standard-http") %>>
<a href="/docs/backends/types/http.html">http</a>
</li>
<li<%= sidebar_current("docs-backends-types-standard-local") %>>
<a href="/docs/backends/types/local.html">local</a>
</li>
<li<%= sidebar_current("docs-backends-types-standard-manta") %>>
<a href="/docs/backends/types/manta.html">manta</a>
</li>