From d4ac68423c4998279f33404db46809d27a5c2362 Mon Sep 17 00:00:00 2001 From: Martin Atkins Date: Mon, 25 Jun 2018 17:57:08 -0700 Subject: [PATCH] website: Tweak the language we use to describe remote state After some discussion with "iamakulov" on Twitter it seems that the use of the word "conflicts" and "merge conflicts" here was sounding like us implicitly condoning the use of version control as a mechanism for distributing local state files, which hasn't been recommended for quite some time since remote state now provides a much more robust solution. While here, I also tweaked some other language on this page for style and for use of terminology we more commonly use in our more recent documentation. --- website/docs/state/purpose.html.md | 47 ++++++++++++++------------ website/docs/state/remote.html.md | 54 +++++++++++++++++++----------- 2 files changed, 59 insertions(+), 42 deletions(-) diff --git a/website/docs/state/purpose.html.md b/website/docs/state/purpose.html.md index a8647006e..e541490b6 100644 --- a/website/docs/state/purpose.html.md +++ b/website/docs/state/purpose.html.md @@ -23,7 +23,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. When you have a resource `resource "aws_instance" "foo"` in your configuration, Terraform uses this map to know that instance `i-abcd1234` -is that resource. +is represented by that resource. For some providers like AWS, Terraform could theoretically use something like AWS tags. Early prototypes of Terraform actually had no state files and used @@ -32,35 +32,35 @@ a simple one: not all resources support tags, and not all cloud providers support tags. Therefore, for mapping configuration to resources in the real world, -Terraform requires states. +Terraform uses its own state structure. ## Metadata -Terraform needs to store more than just resource mappings. Terraform -must keep track of metadata such as dependencies. +Alongside the mappings between resources and remote objects, Terraform must +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 -the configuration no longer exists, it no longer knows the proper destruction -order. +the configuration no longer exists, the order cannot be determined from the +configuration alone. -To work around this, Terraform stores the creation-time dependencies within -the state. Now, when you delete one or more items from the configuration, -Terraform can still build the correct destruction ordering based only -on the state. +To ensure correct operation, Terraform retains a copy of the most recent set +of dependencies within the state. Now Terraform can still determine the correct +order for destruction from the state when you delete one or more items from +the configuration. -One idea to avoid this is for Terraform to understand the proper ordering -of resources. For example, Terraform could know that servers must be deleted -before the subnets they are a part of. The complexity for this approach +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 understand the ordering _across providers_. -In addition to dependencies, Terraform will store more metadata in the -future such as last run time, creation time, update time, lifecycle options -such as prevent destroy, etc. +Terraform also stores other metadata for similar reasons, such as a pointer +to the provider configuration that was most recently used with the resource +in situations where multiple aliased providers are present. ## Performance @@ -88,11 +88,14 @@ state is treated as the record of truth. ## Syncing -The primary motivation people have for using remote state files is in an attempt -to improve using Terraform with teams. State files can easily result in -conflicts when two people modify infrastructure at the same time. +In the default configuration, Terraform stores the state in a file in the +current working directory where Terraform was run. This is okay for getting +started, but when using Terraform in a team it is important for everyone +to be working with the same state so that operations will be applied to the +same remote objects. [Remote state](/docs/state/remote.html) is the recommended solution -to this problem. At the time of writing, remote state works well but there -are still scenarios that can result in state conflicts. A priority for future -versions of Terraform is to improve this. +to this problem. With a fully-featured state backend, Terraform can use +remote locking as a measure to avoid two or more different users accidentally +running Terraform at the same time, and thus ensure that each Terraform run +begins with the most recent updated state. diff --git a/website/docs/state/remote.html.md b/website/docs/state/remote.html.md index 1f4c24664..9cb565ec0 100644 --- a/website/docs/state/remote.html.md +++ b/website/docs/state/remote.html.md @@ -8,19 +8,21 @@ description: |- # Remote State -By default, Terraform stores state locally in a file named "terraform.tfstate". -Because this file must exist, it makes working with Terraform in a team -complicated since it is a frequent source of merge conflicts. Remote state -helps alleviate these issues. +By default, Terraform stores state locally in a file named `terraform.tfstate`. +When working with Terraform in a team, use of a local file makes Terraform +usage complicated because each user must make sure they always have the latest +state data before running Terraform and make sure that nobody else runs +Terraform at the same time. -With remote state, Terraform stores the state in a remote store. Terraform -supports storing state in [Terraform Enterprise](https://www.hashicorp.com/products/terraform/), -[Consul](https://www.consul.io), S3, and more. +With _remote_ state, Terraform writes the state data to a remote data store, +which can then be shared between all members of a team. Terraform supports +storing state in [Terraform Enterprise](https://www.hashicorp.com/products/terraform/), +[HashiCorp Consul](https://www.consul.io/), Amazon S3, and more. Remote state is a feature of [backends](/docs/backends). Configuring and -using backends is easy and you can get started with remote state quickly. -If you want to migrate back to using local state, backends make that -easy as well. +using remote backends is easy and you can get started with remote state +quickly. If you then want to migrate back to using local state, backends make +that easy as well. ## Delegation and Teamwork @@ -31,7 +33,8 @@ your infrastructure to be more easily broken down into components that multiple teams can access. Put another way, remote state also allows teams to share infrastructure -resources in a read-only way. +resources in a read-only way without relying on any additional configuration +store. For example, a core infrastructure team can handle building the core machines, networking, etc. and can expose some information to other @@ -39,16 +42,27 @@ teams to run their own infrastructure. As a more specific example with AWS: you can expose things such as VPC IDs, subnets, NAT instance IDs, etc. through remote state and have other Terraform states consume that. -For example usage see the -[terraform_remote_state](/docs/providers/terraform/d/remote_state.html) data source. +For example usage, see +[the `terraform_remote_state` data source](/docs/providers/terraform/d/remote_state.html). + +While remote state is a convenient, built-in mechanism for sharing data +between configurations, it is also possible to use more general stores to +pass settings both to other configurations and to other consumers. For example, +if your environment has [HashiCorp Consul](https://www.consul.io/) then you +can have one Terraform configuration that writes to Consul using +[`consul_key_prefix`](/docs/providers/consul/r/key_prefix.html) and then +another that consumes those values using +[the `consul_keys` data source](/docs/providers/consul/d/keys.html). ## Locking and Teamwork -Terraform will automatically lock state depending on the -[backend](/docs/backends) used. Please see the full page dedicated -to [state locking](/docs/state/locking.html). +For fully-featured remote backends, Terraform can also use +[state locking](/docs/state/locking.html) to prevent concurrent runs of +Terraform against the same state. -[Terraform Enterprise by HashiCorp](https://www.hashicorp.com/products/terraform/) is a commercial offering -that in addition to locking supports remote operations that allow you to -safely queue Terraform operations in a central location. This enables -teams to safely modify infrastructure concurrently. +[Terraform Enterprise by HashiCorp](https://www.hashicorp.com/products/terraform/) +is a commercial offering that supports an even stronger locking concept that +can also detect attempts to create a new plan when an existing plan is already +awaiting approval, by queuing Terraform operations in a central location. +This allows teams to more easily coordinate and communicate about changes to +infrastructure.