diff --git a/website/source/docs/state/index.html.md b/website/source/docs/state/index.html.md new file mode 100644 index 000000000..f1847702d --- /dev/null +++ b/website/source/docs/state/index.html.md @@ -0,0 +1,35 @@ +--- +layout: "docs" +page_title: "State" +sidebar_current: "docs-state" +description: |- + Terraform stores state which caches the known state of the world the last time Terraform ran. +--- + +# State + +Terraform stores the state of your managed infrastructure from the last +time Terraform was run. By default this state is stored in a local file +named "terraform.tfstate", but it can also be stored remotely, which works +better in a team environment. + +Terraform uses this local state to create plans and make changes to your +infrastructure. Prior to any operation, Terraform does a +[refresh](/docs/commands/refresh.html) to update the state with the +real infrastructure. + +-> **Note:** Terraform currently requires the state to exist after Terraform +has been run. Technically, +at some point in the future, Terraform should be able to populate the local +state file with the real infrastructure if the file didn't exist. But currently, +Terraform state is a mixture of both a cache and required configuration and +isn't optional. + +## Format + +The state is in JSON format and Terraform will promise backwards compatibility +with the state file. The JSON format makes it easy to write tools around the +state if you want or to modify it by hand in the case of a Terraform bug. +The "version" field on the state contents allows us to transparently move +the format forward if we make modifications. + diff --git a/website/source/docs/state/remote.html.md b/website/source/docs/state/remote.html.md new file mode 100644 index 000000000..c0508ba99 --- /dev/null +++ b/website/source/docs/state/remote.html.md @@ -0,0 +1,76 @@ +--- +layout: "docs" +page_title: "Remote State" +sidebar_current: "docs-state-remote" +description: |- + Terraform can store the state remotely, making it easier to version and work with in a team. +--- + +# 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. + +With remote state, Terraform stores the state in a remote store. Terraform +supports storing state in [Atlas](https://atlas.hashicorp.com), +[Consul](https://www.consul.io), S3, and more. + +You can begin using remote state from the beginning with flags to the +[init](/docs/commands/init.html) command, or you can migrate an existing +local state to remote state using the +[remote config](/docs/commands/remote-config.html) command. You can also +use the remote config to disable remote state and move back to local +state. + +## Delegation and Teamwork + +Remote state gives you more than just easier version control and +safer storage. It also allows you to delegate the +[outputs](/docs/configuration/outputs.html) to other teams. This allows +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. + +For example, a core infrastructure team can handle building the core +machines, networking, etc. and can expose some information to other +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. + +An example is shown below: + +``` +resource "terraform_remote_state" "vpc" { + backend = "atlas" + config { + path = "hashicorp/vpc-prod" + } +} + +resource "aws_instance" "foo" { + # ... + subnet_id = "${terraform_state.vpc.output.subnet_id}" +} +``` + +This makes teamwork and componentization of infrastructure frictionless +within your infrastructure. + +## Locking and Teamwork + +Remote state currently **does not** lock regions of your infrastructure +to allow parallel modification using Terraform. Therefore, you must still +collaborate with teammates to safely run Terraform. + +[Atlas by HashiCorp](https://atlas.hashicorp.com) is a commercial offering +that does safely allow parallel Terraform runs and handles infrastructure +locking for you. + +In the future, we'd like to extend the remote state system to allow some +minimal locking functionality, but it is a difficult problem without a +central system that we currently aren't focused on solving. + diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index c60416394..b7af63fc2 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -105,6 +105,15 @@ +