From bd4425657e272447bbc90cf59381f45a84d2695f Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Tue, 14 Feb 2017 16:09:00 -0800 Subject: [PATCH] website: backend state docs --- website/source/docs/backends/config.html.md | 2 +- .../source/docs/backends/operations.html.md | 19 ++++++ website/source/docs/backends/state.html.md | 63 +++++++++++++++++++ website/source/layouts/docs.erb | 10 +-- 4 files changed, 89 insertions(+), 5 deletions(-) create mode 100644 website/source/docs/backends/operations.html.md create mode 100644 website/source/docs/backends/state.html.md diff --git a/website/source/docs/backends/config.html.md b/website/source/docs/backends/config.html.md index ef4087b19..94334d3f7 100644 --- a/website/source/docs/backends/config.html.md +++ b/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 diff --git a/website/source/docs/backends/operations.html.md b/website/source/docs/backends/operations.html.md new file mode 100644 index 000000000..948e7c965 --- /dev/null +++ b/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! diff --git a/website/source/docs/backends/state.html.md b/website/source/docs/backends/state.html.md new file mode 100644 index 000000000..d9431a8b6 --- /dev/null +++ b/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. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 1dbebe78b..dd6303475 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -473,13 +473,15 @@ Configuration - > - Sources + > + State Storage & Locking - > - Creating backends +