github.com/pdecat/terraform@v0.11.9-beta1/website/docs/backends/state.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Backends: State Storage and Locking"
     4  sidebar_current: "docs-backends-state"
     5  description: |-
     6    Backends are configured directly in Terraform files in the `terraform` section.
     7  ---
     8  
     9  # State Storage and Locking
    10  
    11  Backends are responsible for storing state and providing an API for
    12  [state locking](/docs/state/locking.html). State locking is optional.
    13  
    14  Despite the state being stored remotely, all Terraform commands such
    15  as `terraform console`, the `terraform state` operations, `terraform taint`,
    16  and more will continue to work as if the state was local.
    17  
    18  ## State Storage
    19  
    20  Backends determine where state is stored. For example, the local (default)
    21  backend stores state in a local JSON file on disk. The Consul backend stores
    22  the state within Consul. Both of these backends happen to provide locking:
    23  local via system APIs and Consul via locking APIs.
    24  
    25  When using a non-local backend, Terraform will not persist the state anywhere
    26  on disk except in the case of a non-recoverable error where writing the state
    27  to the backend failed. This behavior is a major benefit for backends: if
    28  sensitive values are in your state, using a remote backend allows you to use
    29  Terraform without that state ever being persisted to disk.
    30  
    31  In the case of an error persisting the state to the backend, Terraform will
    32  write the state locally. This is to prevent data loss. If this happens the
    33  end user must manually push the state to the remote backend once the error
    34  is resolved.
    35  
    36  ## Manual State Pull/Push
    37  
    38  You can still manually retrieve the state from the remote state using
    39  the `terraform state pull` command. This will load your remote state and
    40  output it to stdout. You can choose to save that to a file or perform any
    41  other operations.
    42  
    43  You can also manually write state with `terraform state push`. **This
    44  is extremely dangerous and should be avoided if possible.** This will
    45  overwrite the remote state. This can be used to do manual fixups if necessary.
    46  
    47  When manually pushing state, Terraform will attempt to protect you from
    48  some potentially dangerous situations:
    49  
    50    * **Differing lineage**: The "lineage" is a unique ID assigned to a state
    51      when it is created. If a lineage is different, then it means the states
    52      were created at different times and its very likely you're modifying a
    53      different state. Terraform will not allow this.
    54  
    55    * **Higher serial**: Every state has a monotonically increasing "serial"
    56      number. If the destination state has a higher serial, Terraform will
    57      not allow you to write it since it means that changes have occurred since
    58      the state you're attempting to write.
    59  
    60  Both of these protections can be bypassed with the `-force` flag if you're
    61  confident you're making the right decision. Even if using the `-force` flag,
    62  we recommend making a backup of the state with `terraform state pull`
    63  prior to forcing the overwrite.
    64  
    65  ## State Locking
    66  
    67  Backends are responsible for supporting [state locking](/docs/state/locking.html)
    68  if possible. Not all backend types support state locking. In the
    69  [list of supported backend types](/docs/backends/types) we explicitly note
    70  whether locking is supported.
    71  
    72  For more information on state locking, view the
    73  [page dedicated to state locking](/docs/state/locking.html).