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.