Terraform's design assumes that each remote object in Terraform's care is
bound to one resource instance and one alone. If the same object is bound
to multiple instances then confusing behavior will often result, such as
two resource configurations competing to update a single object, or
objects being "left behind" when all existing Terraform deployments are
destroyed.
This assumption was previously only implied, though. This change is an
attempt to be more explicit about it, although these are additions to some
older documentation sections that have not been revised for some time and
so this is just a best effort to make this information discoverable
without getting drawn into a full-on reorganization of these sections.
While revising this there were some particular oddities that I decided to
revise while I was there, but I'll leave a fuller revision of this older
content for a later commit when we have more time to review it in greater
detail.
A proposed pull request to the AWS provider would change the import behavior of
`aws_security_group`. This preemptive change will help keep the docs accurate if
that gets merged.
As mentioned in #17871 the current example can hide the fact that the module
path plays an important role. The example's explanation is expanded.
Moreover, the verb "attach" is replaced with "map" to make the vocabulary
consistent with the wording in the documentation of the terraform state.
In the terraform state documentation the verb "map" is widely used to
describe the relationship between an item in the state and in the real world
whereas the verb "attach" is not used anywhere.
Based on feedback from #15569 that the previous example was too abstract
and did not give enough context about what each of the different arguments
mean and how they generalize to other resource types.
Martin Atkins