ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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.
This commit is contained in:
Martin Atkins 2018-06-25 17:57:08 -07:00
parent e2373c8073
commit d4ac68423c
2 changed files with 59 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
website/docs/state/purpose.html.md
View File

@ -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 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 world. When you have a resource `resource "aws_instance" "foo"` in your
configuration, Terraform uses this map to know that instance `i-abcd1234` 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 For some providers like AWS, Terraform could theoretically use something like
AWS tags. Early prototypes of Terraform actually had no state files and used 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. support tags.
Therefore, for mapping configuration to resources in the real world, Therefore, for mapping configuration to resources in the real world,
Terraform requires states. Terraform uses its own state structure.
## Metadata ## Metadata
Terraform needs to store more than just resource mappings. Terraform Alongside the mappings between resources and remote objects, Terraform must
must keep track of metadata such as dependencies. also track metadata such as resource dependencies.
Terraform typically uses the configuration to determine dependency order. Terraform typically uses the configuration to determine dependency order.
However, when you delete a resource from a Terraform configuration, Terraform 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 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 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 the configuration no longer exists, the order cannot be determined from the
order. configuration alone.
To work around this, Terraform stores the creation-time dependencies within To ensure correct operation, Terraform retains a copy of the most recent set
the state. Now, when you delete one or more items from the configuration, of dependencies within the state. Now Terraform can still determine the correct
Terraform can still build the correct destruction ordering based only order for destruction from the state when you delete one or more items from
on the state. the configuration.
One idea to avoid this is for Terraform to understand the proper ordering One way to avoid this would be for Terraform to know a required ordering
of resources. For example, Terraform could know that servers must be deleted between resource types. For example, Terraform could know that servers must be
before the subnets they are a part of. The complexity for this approach 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 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 cloud, Terraform must also
understand the ordering _across providers_. understand the ordering _across providers_.
In addition to dependencies, Terraform will store more metadata in the Terraform also stores other metadata for similar reasons, such as a pointer
future such as last run time, creation time, update time, lifecycle options to the provider configuration that was most recently used with the resource
such as prevent destroy, etc. in situations where multiple aliased providers are present.
## Performance ## Performance
@ -88,11 +88,14 @@ state is treated as the record of truth.
## Syncing ## Syncing
The primary motivation people have for using remote state files is in an attempt In the default configuration, Terraform stores the state in a file in the
to improve using Terraform with teams. State files can easily result in current working directory where Terraform was run. This is okay for getting
conflicts when two people modify infrastructure at the same time. 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 [Remote state](/docs/state/remote.html) is the recommended solution
to this problem. At the time of writing, remote state works well but there to this problem. With a fully-featured state backend, Terraform can use
are still scenarios that can result in state conflicts. A priority for future remote locking as a measure to avoid two or more different users accidentally
versions of Terraform is to improve this. running Terraform at the same time, and thus ensure that each Terraform run
begins with the most recent updated state.

54
website/docs/state/remote.html.md
View File

@ -8,19 +8,21 @@ description: |-
# Remote State # Remote State
By default, Terraform stores state locally in a file named "terraform.tfstate". 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 When working with Terraform in a team, use of a local file makes Terraform
complicated since it is a frequent source of merge conflicts. Remote state usage complicated because each user must make sure they always have the latest
helps alleviate these issues. 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 With _remote_ state, Terraform writes the state data to a remote data store,
supports storing state in [Terraform Enterprise](https://www.hashicorp.com/products/terraform/), which can then be shared between all members of a team. Terraform supports
[Consul](https://www.consul.io), S3, and more. 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 Remote state is a feature of [backends](/docs/backends). Configuring and
using backends is easy and you can get started with remote state quickly. using remote backends is easy and you can get started with remote state
If you want to migrate back to using local state, backends make that quickly. If you then want to migrate back to using local state, backends make
easy as well. that easy as well.
## Delegation and Teamwork ## Delegation and Teamwork
@ -31,7 +33,8 @@ your infrastructure to be more easily broken down into components that
multiple teams can access. multiple teams can access.
Put another way, remote state also allows teams to share infrastructure 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 For example, a core infrastructure team can handle building the core
machines, networking, etc. and can expose some information to other 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 you can expose things such as VPC IDs, subnets, NAT instance IDs, etc. through
remote state and have other Terraform states consume that. remote state and have other Terraform states consume that.
For example usage see the For example usage, see
[terraform_remote_state](/docs/providers/terraform/d/remote_state.html) data source. [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 ## Locking and Teamwork
Terraform will automatically lock state depending on the For fully-featured remote backends, Terraform can also use
[backend](/docs/backends) used. Please see the full page dedicated [state locking](/docs/state/locking.html) to prevent concurrent runs of
to [state locking](/docs/state/locking.html). Terraform against the same state.
[Terraform Enterprise by HashiCorp](https://www.hashicorp.com/products/terraform/) is a commercial offering [Terraform Enterprise by HashiCorp](https://www.hashicorp.com/products/terraform/)
that in addition to locking supports remote operations that allow you to is a commercial offering that supports an even stronger locking concept that
safely queue Terraform operations in a central location. This enables can also detect attempts to create a new plan when an existing plan is already
teams to safely modify infrastructure concurrently. awaiting approval, by queuing Terraform operations in a central location.
This allows teams to more easily coordinate and communicate about changes to
infrastructure.