website: document state

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

@@ -0,0 +1,35 @@
+---
+layout: "docs"
+page_title: "State"
+sidebar_current: "docs-state"
+description: |-
+  Terraform stores state which caches the known state of the world the last time Terraform ran.
+---
+
+# State
+
+Terraform stores the state of your managed infrastructure from the last
+time Terraform was run. By default this state is stored in a local file
+named "terraform.tfstate", but it can also be stored remotely, which works
+better in a team environment.
+
+Terraform uses this local state to create plans and make changes to your
+infrastructure. Prior to any operation, Terraform does a
+[refresh](/docs/commands/refresh.html) to update the state with the
+real infrastructure.
+
+-> **Note:** Terraform currently requires the state to exist after Terraform
+has been run. Technically,
+at some point in the future, Terraform should be able to populate the local
+state file with the real infrastructure if the file didn't exist. But currently,
+Terraform state is a mixture of both a cache and required configuration and
+isn't optional.
+
+## Format
+
+The state is in JSON format and Terraform will promise backwards compatibility
+with the state file. The JSON format makes it easy to write tools around the
+state if you want or to modify it by hand in the case of a Terraform bug.
+The "version" field on the state contents allows us to transparently move
+the format forward if we make modifications.
+

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

@@ -0,0 +1,76 @@
+---
+layout: "docs"
+page_title: "Remote State"
+sidebar_current: "docs-state-remote"
+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.
+
+An example is shown below:
+
+```
+resource "terraform_remote_state" "vpc" {
+    backend = "atlas"
+    config {
+        path = "hashicorp/vpc-prod"
+    }
+}
+
+resource "aws_instance" "foo" {
+    # ...
+    subnet_id = "${terraform_state.vpc.output.subnet_id}"
+}
+```
+
+This makes teamwork and componentization of infrastructure frictionless
+within your infrastructure.
+
+## 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/layouts/docs.erb

@@ -105,6 +105,15 @@
 				</ul>
 				</li>
 
+				<li<%= sidebar_current("docs-state") %>>
+					<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>
+						</li>
+					</ul>
+				</li>
+
 				<li<%= sidebar_current("docs-providers") %>>
 				<a href="/docs/providers/index.html">Providers</a>
                 <ul class="nav">