github.com/iaas-resource-provision/iaas-rpc@v1.0.7-0.20211021023331-ed21f798c408/website/docs/language/state/index.html.md (about)

     1  ---
     2  layout: "language"
     3  page_title: "State"
     4  sidebar_current: "docs-state"
     5  description: |-
     6    Terraform must store state about your managed infrastructure and configuration. This state is used by Terraform to map real world resources to your configuration, keep track of metadata, and to improve performance for large infrastructures.
     7  ---
     8  
     9  # State
    10  
    11  Terraform must store state about your managed infrastructure and
    12  configuration. This state is used by Terraform to map real world
    13  resources to your configuration, keep track of metadata, and to improve
    14  performance for large infrastructures.
    15  
    16  This state is stored by default in a local file named "resource_state.json",
    17  but it can also be stored remotely, which works better in a team environment.
    18  
    19  Terraform uses this local state to create plans and make changes to your
    20  infrastructure. Prior to any operation, Terraform does a
    21  [refresh](/docs/cli/commands/refresh.html) to update the state with the
    22  real infrastructure.
    23  
    24  The primary purpose of Terraform state is to store bindings between objects in
    25  a remote system and resource instances declared in your configuration.
    26  When Terraform creates a remote object in response to a change of configuration,
    27  it will record the identity of that remote object against a particular
    28  resource instance, and then potentially update or delete that object in
    29  response to future configuration changes.
    30  
    31  For more information on why Terraform requires state and why Terraform cannot
    32  function without state, please see the page [state purpose](/docs/language/state/purpose.html).
    33  
    34  ## Inspection and Modification
    35  
    36  While the format of the state files are just JSON, direct file editing
    37  of the state is discouraged. Terraform provides the
    38  [terraform state](/docs/cli/commands/state/index.html) command to perform
    39  basic modifications of the state using the CLI.
    40  
    41  The CLI usage and output of the state commands is structured to be
    42  friendly for Unix tools such as grep, awk, etc. Additionally, the CLI
    43  insulates users from any format changes within the state itself. The Terraform
    44  project will keep the CLI working while the state format underneath it may
    45  shift.
    46  
    47  Terraform expects a one-to-one mapping between configured resource instances
    48  and remote objects. Normally that is guaranteed by Terraform being the one
    49  to create each object and record its identity in the state, or to destroy
    50  an object and then remove the binding for it.
    51  
    52  If you add or remove bindings in the state by other means, such as by importing
    53  externally-created objects with `terraform import`, or by asking Terraform to
    54  "forget" an existing object with `terraform state rm`, you'll then need to
    55  ensure for yourself that this one-to-one rule is followed, such as by manually
    56  deleting an object that you asked Terraform to "forget", or by re-importing it
    57  to bind it to some other resource instance.
    58  
    59  ## Format
    60  
    61  State snapshots are stored in JSON format and new Terraform versions are
    62  generally backward compatible with state snapshots produced by earlier versions.
    63  However, the state format is subject to change in new Terraform versions, so
    64  if you build software that parses or modifies it directly you should expect
    65  to perform ongoing maintenance of that software as the state format evolves
    66  in new versions.
    67  
    68  Alternatively, there are several integration points which produce JSON output
    69  that is specifically intended for consumption by external software:
    70  
    71  * [The `terraform output` command](/docs/cli/commands/output.html)
    72  has a `-json` option, for obtaining either the full set of root module output
    73  values or a specific named output value from the latest state snapshot.
    74  * [The `terraform show` command](/docs/cli/commands/show.html) has a `-json`
    75  option for inspecting the latest state snapshot in full, and also for
    76  inspecting saved plan files which include a copy of the prior state at the
    77  time the plan was made.
    78  
    79  A typical way to use these in situations where Terraform is running in
    80  automation is to run them immediately after a successful `terraform apply`
    81  to obtain a representation of the latest state snapshot, and then store that
    82  result as an artifact associated with the automated run so that other software
    83  can potentially consume it without needing to run Terraform itself.