From 00f5110a498541b9369dc1be0d64ce591bba5939 Mon Sep 17 00:00:00 2001 From: Mukesh Kumar Date: Thu, 30 Dec 2021 14:47:57 +0530 Subject: [PATCH 1/5] Update purpose.mdx The document is less intuitive for beginners . I've added contents to make the document more lucid. --- website/docs/language/state/purpose.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/website/docs/language/state/purpose.mdx b/website/docs/language/state/purpose.mdx index 95e8f09d4f..94b70e2e92 100644 --- a/website/docs/language/state/purpose.mdx +++ b/website/docs/language/state/purpose.mdx @@ -11,7 +11,7 @@ description: >- State is a necessary requirement for Terraform to function. It is often asked if it is possible for Terraform to work without state, or for Terraform -to not use state and just inspect cloud resources on every run. This page +to not use state and just inspect real world resources on every run. This page will help explain why Terraform state is required. As you'll see from the reasons below, state is required. And in the scenarios @@ -22,9 +22,9 @@ shifting massive amounts of complexity from one place (state) to another place ## Mapping to the Real World Terraform requires some sort of database to map Terraform config to the real -world. When you have a resource `resource "aws_instance" "foo"` in your -configuration, Terraform uses this map to know that instance `i-abcd1234` -is represented by that resource. +world. For example, when you have a resource `resource "aws_instance" "foo"` in your +configuration, Terraform uses this mapping to know that the resource `resource "aws_instance" "foo"` +represents a real world object having instance ID `i-abcd1234` on a remote system. For some providers like AWS, Terraform could theoretically use something like AWS tags. Early prototypes of Terraform actually had no state files and used @@ -35,8 +35,8 @@ 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 +Terraform expects that each remote object on the provider is bound to only one resource +instance in the configuration, which is normally guaranteed since Terraform is 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 @@ -53,8 +53,8 @@ also track metadata such as resource dependencies. Terraform typically uses the configuration to determine dependency order. However, when you delete a resource from a Terraform configuration, Terraform -must know how to delete that resource. Terraform can see that a mapping exists -for a resource not in your configuration and plan to destroy. However, since +must know how to delete that resource from the remote system. Terraform can see that a mapping exists +in the state file for a resource not in your configuration and plan to destroy. However, since the configuration no longer exists, the order cannot be determined from the configuration alone. @@ -67,7 +67,7 @@ One way to avoid this would be for Terraform to know a required ordering between resource types. For example, Terraform could know that servers must be deleted before the subnets they are a part of. The complexity for this approach quickly explodes, however: in addition to Terraform having to understand the -ordering semantics of every resource for every cloud, Terraform must also +ordering semantics of every resource for every _providers_, Terraform must also understand the ordering _across providers_. Terraform also stores other metadata for similar reasons, such as a pointer From 24af4e447fd1a6b840479c0f9070804b1002186e Mon Sep 17 00:00:00 2001 From: Mukesh Kumar Date: Wed, 19 Jan 2022 11:49:10 +0530 Subject: [PATCH 2/5] Update website/docs/language/state/purpose.mdx _provider_ is appropriate here. Co-authored-by: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> --- website/docs/language/state/purpose.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/language/state/purpose.mdx b/website/docs/language/state/purpose.mdx index 94b70e2e92..21639a1404 100644 --- a/website/docs/language/state/purpose.mdx +++ b/website/docs/language/state/purpose.mdx @@ -67,7 +67,7 @@ One way to avoid this would be for Terraform to know a required ordering between resource types. For example, Terraform could know that servers must be deleted before the subnets they are a part of. The complexity for this approach quickly explodes, however: in addition to Terraform having to understand the -ordering semantics of every resource for every _providers_, Terraform must also +ordering semantics of every resource for every _provider_, Terraform must also understand the ordering _across providers_. Terraform also stores other metadata for similar reasons, such as a pointer From 0b178d586733bf4e74f04646e0382236c659d176 Mon Sep 17 00:00:00 2001 From: Mukesh Kumar Date: Wed, 19 Jan 2022 11:49:25 +0530 Subject: [PATCH 3/5] Update website/docs/language/state/purpose.mdx Co-authored-by: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> --- website/docs/language/state/purpose.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/language/state/purpose.mdx b/website/docs/language/state/purpose.mdx index 21639a1404..cc68a17ccc 100644 --- a/website/docs/language/state/purpose.mdx +++ b/website/docs/language/state/purpose.mdx @@ -24,7 +24,7 @@ shifting massive amounts of complexity from one place (state) to another place Terraform requires some sort of database to map Terraform config to the real world. For example, when you have a resource `resource "aws_instance" "foo"` in your configuration, Terraform uses this mapping to know that the resource `resource "aws_instance" "foo"` -represents a real world object having instance ID `i-abcd1234` on a remote system. +represents a real world object with the instance ID `i-abcd1234` on a remote system. For some providers like AWS, Terraform could theoretically use something like AWS tags. Early prototypes of Terraform actually had no state files and used From 149e5abe37bac7ffc649a75aac2b68064a0c80b2 Mon Sep 17 00:00:00 2001 From: Mukesh Kumar Date: Wed, 19 Jan 2022 12:41:29 +0530 Subject: [PATCH 4/5] Update purpose.mdx updated the document as per suggestion by Craig. --- website/docs/language/state/purpose.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/language/state/purpose.mdx b/website/docs/language/state/purpose.mdx index cc68a17ccc..a4eedaba06 100644 --- a/website/docs/language/state/purpose.mdx +++ b/website/docs/language/state/purpose.mdx @@ -35,8 +35,8 @@ support tags. Therefore, for mapping configuration to resources in the real world, Terraform uses its own state structure. -Terraform expects that each remote object on the provider is bound to only one resource -instance in the configuration, which is normally guaranteed since Terraform is responsible for +Terraform expects that each remote object is bound to only one resource +instance in the configuration, which is normally guaranteed by Terraform since Terraform is 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 From 5b35c8c0984dd5bbfb8c6715bd698240fa300c6a Mon Sep 17 00:00:00 2001 From: Mukesh Kumar Date: Fri, 28 Jan 2022 19:15:12 +0530 Subject: [PATCH 5/5] Update purpose.mdx Update "Mapping to the Real World" section --- website/docs/language/state/purpose.mdx | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/website/docs/language/state/purpose.mdx b/website/docs/language/state/purpose.mdx index a4eedaba06..45fef6cb25 100644 --- a/website/docs/language/state/purpose.mdx +++ b/website/docs/language/state/purpose.mdx @@ -35,16 +35,12 @@ 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 in the configuration, which is normally guaranteed by Terraform since Terraform is 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. +Terraform expects that each remote object is bound to only one resource instance in the configuration. +If a remote object is bound to multiple resource instances, the mapping from configuration to the remote +object in the state becomes ambiguous, and Terraform may behave unexpectedly. Terraform can guarantee +a one-to-one mapping when it creates objects and records their identities in the state. +When importing objects created outside of Terraform, you must make sure that each distinct object +is imported to only one resource instance. ## Metadata