terraform/website/source/docs/state/remote.html.md

layout	page_title	sidebar_current	description
docs	Remote State	docs-state-remote	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, Consul, S3, and more.

You can begin using remote state from the beginning with flags to the init command, or you can migrate an existing local state to remote state using the remote config 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 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_remote_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 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.