terraform/website/source/docs/backends/types/s3.html.md

layout	page_title	sidebar_current	description
backend-types	Backend Type: s3	docs-backends-types-standard-s3	Terraform can store state remotely in S3 and lock that state with DynamoDB.

S3

Kind: Standard (with locking via DynamoDB)

Stores the state as a given key in a given bucket on Amazon S3. This backend also supports state locking via Dynamo DB.

~> 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.

Example Configuration

terraform {
  backend "s3" {
    bucket = "mybucket"
    key    = "path/to/my/key"
    region = "us-east-1"
  }
}

This assumes we have a bucket created called mybucket. The Terraform state is written to the key path/to/my/key.

Note that for the access credentials we recommend using a partial configuration.

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.
• lock_table - (Optional) The name of a DynamoDB table to use for state locking. The table must have a primary key named LockID.
• 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.
• role_arn - (Optional) The role to be assumed