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

layout	page_title	sidebar_current	description
remotestate	Remote State Backend: s3	docs-state-remote-s3	Terraform can store the state remotely, making it easier to version and work with in a team.

S3

Stores the state as a given key in a given bucket on Amazon S3.

~> Warning! It is highly recommended that you enable Bucket Versioning on the S3 bucket to allow for state recovery in the case of accidental deletions and human error.

Using S3 for Remote State

To enable remote state on S3 we run the terraform remote config command like so:

terraform remote config \
	-backend=s3 \
	-backend-config="bucket=terraform-state-prod" \
	-backend-config="key=network/terraform.tfstate" \
	-backend-config="region=us-east-1"

This assumes we have a bucket created called terraform-state-prod. The Terraform state is written to the file terraform.tfstate in a folder called network.

-> Note: Passing credentials directly via configuration options will make them included in cleartext inside the persisted state. Use of environment variables or a configuration file is recommended.

Using the S3 remote state

To make use of the S3 remote state we can use the terraform_remote_state data source.

data "terraform_remote_state" "foo" {
	backend = "s3"
	config {
		bucket = "terraform-state-prod"
		key = "network/terraform.tfstate"
		region = "us-east-1"
	}
}

The terraform_remote_state data source will return all of the root outputs defined in the referenced remote state, an example output might look like:

data.terraform_remote_state.network:
  id = 2016-10-29 01:57:59.780010914 +0000 UTC
  addresses.# = 2
  addresses.0 = 52.207.220.222
  addresses.1 = 54.196.78.166
  backend = s3
  config.% = 3
  config.bucket = terraform-state-prod
  config.key = network/terraform.tfstate
  config.region = us-east-1
  elb_address = web-elb-790251200.us-east-1.elb.amazonaws.com
  public_subnet_id = subnet-1e05dd33

Configuration variables

The following configuration options or environment variables are supported:

• bucket - (Required) The name of the S3 bucket.
• key - (Required) The path to the state file inside the bucket.
• region / AWS_DEFAULT_REGION - (Optional) The region of the S3 bucket.
• endpoint / AWS_S3_ENDPOINT - (Optional) A custom endpoint for the S3 API.
• encrypt - (Optional) Whether to enable server side encryption of the state file.
• acl - Canned ACL to be applied to the state file.
• access_key / AWS_ACCESS_KEY_ID - (Optional) AWS access key.
• secret_key / AWS_SECRET_ACCESS_KEY - (Optional) AWS secret access key.
• kms_key_id - (Optional) The ARN of a KMS Key to use for encrypting the state.
• profile - (Optional) This is the AWS profile name as set in the shared credentials file.
• shared_credentials_file - (Optional) This is the path to the shared credentials file. If this is not set and a profile is specified, ~/.aws/credentials will be used.
• token - (Optional) Use this to set an MFA token. It can also be sourced from the AWS_SESSION_TOKEN environment variable.