docs: Create new section for remote state backends

radeksimko · radeksimko · commit f2ffff33eb34 · 2016-01-18T08:08:19.000Z
diff --git a/website/source/assets/stylesheets/_docs.scss b/website/source/assets/stylesheets/_docs.scss
@@ -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;
diff --git a/website/source/docs/commands/remote-config.html.markdown b/website/source/docs/commands/remote-config.html.markdown
@@ -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.
diff --git a/website/source/docs/state/remote/artifactory.html.md b/website/source/docs/state/remote/artifactory.html.md
@@ -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
diff --git a/website/source/docs/state/remote/atlas.html.md b/website/source/docs/state/remote/atlas.html.md
@@ -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)
diff --git a/website/source/docs/state/remote/consul.html.md b/website/source/docs/state/remote/consul.html.md
@@ -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`.
diff --git a/website/source/docs/state/remote/etcd.html.md b/website/source/docs/state/remote/etcd.html.md
@@ -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
diff --git a/website/source/docs/state/remote/http.html.md b/website/source/docs/state/remote/http.html.md
@@ -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`.
diff --git a/website/source/docs/state/remote/index.html.md b/website/source/docs/state/remote/index.html.md
@@ -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.
 ---
diff --git a/website/source/docs/state/remote/s3.html.md b/website/source/docs/state/remote/s3.html.md
@@ -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
diff --git a/website/source/docs/state/remote/swift.html.md b/website/source/docs/state/remote/swift.html.md
diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb
diff --git a/website/source/layouts/remotestate.erb b/website/source/layouts/remotestate.erb
