website: backend state docs

website/source/docs/backends/config.html.md

@@ -3,7 +3,7 @@ layout: "docs"
 page_title: "Backends: Configuration"
 sidebar_current: "docs-backends-config"
 description: |-
-  Terraform must initialize any configured backend before use. This can be done by simply running `terraform init`.
+  Backends are configured directly in Terraform files in the `terraform` section.
 ---
 
 # Backend Configuration

website/source/docs/backends/operations.html.md

@@ -0,0 +1,19 @@
+---
+layout: "docs"
+page_title: "Backends: Operations (refresh, plan, apply, etc.)"
+sidebar_current: "docs-backends-ops"
+description: |-
+  Some backends support the ability to run operations (`refresh`, `plan`, `apply`, etc.) remotely. Terraform will continue to look and behave as if they're running locally while they in fact run on a remote machine.
+---
+
+# Operations (plan, apply, etc.)
+
+Some backends support the ability to run operations (`refresh`, `plan`, `apply`,
+etc.) remotely. Terraform will continue to look and behave as if they're
+running locally while they in fact run on a remote machine.
+
+Backends should not modify the actual infrastructure change behavior of
+these commands. They will only modify how they're invoked.
+
+At the time of writing, no backends support this. This shouldn't be linked
+in the sidebar yet!

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

@@ -0,0 +1,63 @@
+---
+layout: "docs"
+page_title: "Backends: State Storage and Locking"
+sidebar_current: "docs-backends-state"
+description: |-
+  Backends are configured directly in Terraform files in the `terraform` section.
+---
+
+# State Storage and Locking
+
+Backends are responsible for storing state and providing an API for
+[state locking](/docs/state/locking.html). State locking is optional.
+
+Despite the state being stored remotely, all Terraform commands such
+as `terraform console`, the `terraform state` operations, `terraform taint`,
+and more will continue to work as if the state was local.
+
+## State Storage
+
+Backends determine where state is stored. For example, the local (default)
+backend stores state in a local JSON file on disk. The Consul backend stores
+the state within Consul. Both of these backends happen to provide locking:
+local via system APIs and Consul via locking APIs.
+
+When using a non-local backend, Terraform will not persist the state anywhere
+on disk except in the case of a non-recoverable error where writing the state
+to the backend failed. This behavior is a major benefit for backends: if
+sensitive values are in your state, using a remote backend allows you to use
+Terraform without that state ever being persisted to disk.
+
+In the case of an error persisting the state to the backend, Terraform will
+write the state locally. This is to prevent data loss. If this happens the
+end user must manually push the state to the remote backend once the error
+is resolved.
+
+## Manual State Pull/Push
+
+You can still manually retrieve the state from the remote state using
+the `terraform state pull` command. This will load your remote state and
+output it to stdout. You can choose to save that to a file or perform any
+other operations.
+
+You can also manually write state with `terraform state push`. **This
+is extremely dangerous and should be avoided if possible.** This will
+overwrite the remote state. This can be used to do manual fixups if necessary.
+
+When manually pushing state, Terraform will attempt to protect you from
+some potentially dangerous situations:
+
+  * **Differing lineage**: The "lineage" is a unique ID assigned to a state
+    when it is created. If a lineage is different, then it means the states
+    were created at different times and its very likely you're modifying a
+    different state. Terraform will not allow this.
+
+  * **Higher serial**: Every state has a monotonically increasing "serial"
+    number. If the destination state has a higher serial, Terraform will
+    not allow you to write it since it means that changes have occurred since
+    the state you're attempting to write.
+
+Both of these protections can be bypassed with the `-force` flag if you're
+confident you're making the right decision. Even if using the `-force` flag,
+we recommend making a backup of the state with `terraform state pull`
+prior to forcing the overwrite.

website/source/layouts/docs.erb

@@ -473,13 +473,15 @@
 							<a href="/docs/backends/config.html">Configuration</a>
 						</li>
 
-						<li<%= sidebar_current("docs-backends-sources") %>>
+						<li<%= sidebar_current("docs-backends-state") %>>
-							<a href="/docs/backends/sources.html">Sources</a>
+							<a href="/docs/backends/state.html">State Storage & Locking</a>
 						</li>
 
-						<li<%= sidebar_current("docs-backends-create") %>>
+						<!--
-							<a href="/docs/backends/create.html">Creating backends</a>
+						<li<%= sidebar_current("docs-backends-ops") %>>
+							<a href="/docs/backends/operations.html">Operations</a>
 						</li>
+						-->
 					</ul>
 				</li>