docs: Create new section for remote state backends

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

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)

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

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

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

website/source/docs/state/remote/index.html.md

@@ -0,0 +1,58 @@
+---
+layout: "remotestate"
+page_title: "Remote State"
+sidebar_current: "docs-state-remote_index"
+description: |-
+  Terraform can store the state remotely, making it easier to version and work with in a team.
+---
+
+# Remote State
+
+By default, Terraform stores state locally in a file named "terraform.tfstate".
+Because this file must exist, it makes working with Terraform in a team
+complicated since it is a frequent source of merge conflicts. Remote state
+helps alleviate these issues.
+
+With remote state, Terraform stores the state in a remote store. Terraform
+supports storing state in [Atlas](https://atlas.hashicorp.com),
+[Consul](https://www.consul.io), S3, and more.
+
+You can begin using remote state from the beginning with flags to the
+[init](/docs/commands/init.html) command, or you can migrate an existing
+local state to remote state using the
+[remote config](/docs/commands/remote-config.html) command. You can also
+use the remote config to disable remote state and move back to local
+state.
+
+## Delegation and Teamwork
+
+Remote state gives you more than just easier version control and
+safer storage. It also allows you to delegate the
+[outputs](/docs/configuration/outputs.html) to other teams. This allows
+your infrastructure to be more easily broken down into components that
+multiple teams can access.
+
+Put another way, remote state also allows teams to share infrastructure
+resources in a read-only way.
+
+For example, a core infrastructure team can handle building the core
+machines, networking, etc. and can expose some information to other
+teams to run their own infrastructure. As a more specific example with AWS:
+you can expose things such as VPC IDs, subnets, NAT instance IDs, etc. through
+remote state and have other Terraform states consume that.
+
+For example usage see the [terraform_remote_state](/docs/providers/terraform/r/remote_state.html) resource.
+
+## Locking and Teamwork
+
+Remote state currently **does not** lock regions of your infrastructure
+to allow parallel modification using Terraform. Therefore, you must still
+collaborate with teammates to safely run Terraform.
+
+[Atlas by HashiCorp](https://atlas.hashicorp.com) is a commercial offering
+that does safely allow parallel Terraform runs and handles infrastructure
+locking for you.
+
+In the future, we'd like to extend the remote state system to allow some
+minimal locking functionality, but it is a difficult problem without a
+central system that we currently aren't focused on solving.

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

website/source/docs/state/remote/swift.html.md

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