Merge pull request #25721 from hashicorp/doc-import-multiple-bindings

website: Documentation about the one-to-one object binding assumption

website/docs/commands/import.html.md

@@ -31,6 +31,14 @@ it is the zone ID (`Z12ABC4UGMOZ2N`). Please reference the provider documentatio
 on the ID format. If you're unsure, feel free to just try an ID. If the ID
 is invalid, you'll just receive an error message.
 
+~> Warning: Terraform expects that each remote object it is managing will be
+bound to only one resource address, which is normally guaranteed by Terraform
+itself having created all objects. If you import existing objects into Terraform,
+be careful to import each remote object to only one Terraform resource address.
+If you import the same object multiple times, Terraform may exhibit unwanted
+behavior. For more information on this assumption, see
+[the State section](/docs/state/).
+
 The command-line flags are all optional. The list of available flags are:
 
 * `-backup=path` - Path to backup the existing state file. Defaults to

website/docs/import/index.html.md

@@ -20,6 +20,14 @@ This is a great way to slowly transition infrastructure to Terraform, or
 to be able to be confident that you can use Terraform in the future if it
 potentially doesn't support every feature you need today.
 
+~> Warning: Terraform expects that each remote object it is managing will be
+bound to only one resource address, which is normally guaranteed by Terraform
+itself having created all objects. If you import existing objects into Terraform,
+be careful to import each remote object to only one Terraform resource address.
+If you import the same object multiple times, Terraform may exhibit unwanted
+behavior. For more information on this assumption, see
+[the State section](/docs/state/).
+
 ## Currently State Only
 
 The current implementation of Terraform import can only import resources

website/docs/import/usage.html.md

@@ -17,6 +17,14 @@ you can't yet point Terraform import to an entire collection of resources
 such as an AWS VPC and import all of it. This workflow will be improved in a
 future version of Terraform.
 
+~> Warning: Terraform expects that each remote object it is managing will be
+bound to only one resource address, which is normally guaranteed by Terraform
+itself having created all objects. If you import existing objects into Terraform,
+be careful to import each remote object to only one Terraform resource address.
+If you import the same object multiple times, Terraform may exhibit unwanted
+behavior. For more information on this assumption, see
+[the State section](/docs/state/).
+
 To import a resource, first write a resource block for it in your
 configuration, establishing the name by which it will be known to Terraform:
 

website/docs/state/index.html.md

@@ -21,6 +21,13 @@ infrastructure. Prior to any operation, Terraform does a
 [refresh](/docs/commands/refresh.html) to update the state with the
 real infrastructure.
 
+The primary purpose of Terraform state is to store bindings between objects in
+a remote system and resource instances declared in your configuration.
+When Terraform creates a remote object in response to a change of configuration,
+it will record the identity of that remote object against a particular
+resource instance, and then potentially update or delete that object in
+response to future configuration changes.
+
 For more information on why Terraform requires state and why Terraform cannot
 function without state, please see the page [state purpose](/docs/state/purpose.html).
 
@@ -37,15 +44,40 @@ insulates users from any format changes within the state itself. The Terraform
 project will keep the CLI working while the state format underneath it may
 shift.
 
-Finally, the CLI manages backups for you automatically. If you make a mistake
+Terraform expects a one-to-one mapping between configured resource instances
-modifying your state, the state CLI will always have a backup available for
+and remote objects. Normally that is guaranteed by Terraform being the one
-you that you can restore.
+to create each object and record its identity in the state, or to destroy
+an object and then remove the binding for it.
+
+If you add or remove bindings in the state by other means, such as by importing
+externally-created objects with `terraform import`, or by asking Terraform to
+"forget" an existing object with `terraform state rm`, you'll then need to
+ensure for yourself that this one-to-one rule is followed, such as by manually
+deleting an object that you asked Terraform to "forget", or by re-importing it
+to bind it to some other resource instance.
 
 ## Format
 
-The state is in JSON format and Terraform will promise backwards compatibility
+State snapshots are stored in JSON format and new Terraform versions are
-with the state file. The JSON format makes it easy to write tools around the
+generally backward compatible with state snapshots produced by earlier versions.
-state if you want or to modify it by hand in the case of a Terraform bug.
+However, the state format is subject to change in new Terraform versions, so
-The "version" field on the state contents allows us to transparently move
+if you build software that parses or modifies it directly you should expect
-the format forward if we make modifications.
+to perform ongoing maintenence of that software as the state format evolves
+in new versions.
 
+Alternatively, there are several integration points which produce JSON output
+that is specifically intended for consumption by external software:
+
+* [The `terraform output` command](/commands/output.html)
+has a `-json` option, for obtaining either the full set of root module output
+values or a specific named output value from the latest state snapshot.
+* [The `terraform show` command](/docs/commands/show.html) has a `-json`
+option for inspecting the latest state snapshot in full, and also for
+inspecting saved plan files which include a copy of the prior state at the
+time the plan was made.
+
+A typical way to use these in situations where Terraform is running in
+automation is to run them immediately after a successful `terraform apply`
+to obtain a representation of the latest state snapshot, and then store that
+result as an artifact associated with the automated run so that other software
+can potentially consume it without needing to run Terraform itself.

website/docs/state/purpose.html.md

@@ -34,6 +34,17 @@ support tags.
 Therefore, for mapping configuration to resources in the real world,
 Terraform uses its own state structure.
 
+Terraform expects that each remote object is bound to only one resource
+instance, which is normally guaranteed by Terraform being responsible for
+creating the objects and recording their identities in the state. If you
+instead import objects that were created outside of Terraform, you'll need
+to check yourself that each distinct object is imported to only one resource
+instance.
+
+If one remote object is bound to two or more resource instances then Terraform
+may take unexpected actions against those objects, because the mapping from
+configuration to the remote object state has become ambiguous.
+
 ## Metadata
 
 Alongside the mappings between resources and remote objects, Terraform must