terraform/website/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 and consistency checking via Dynamo DB, which can be enabled by setting the dynamodb_table field to an existing DynamoDB table name.

~> 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" "network" {
  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. When using a non-default workspace, the state path will be /workspace_key_prefix/workspace_name/key
• 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, Deprecated) Use dynamodb_table instead.
• dynamodb_table - (Optional) The name of a DynamoDB table to use for state locking and consistency. The table must have a primary key named LockID. If not present, locking will be disabled.
• 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.
• assume_role_policy - (Optional) The permissions applied when assuming a role.
• external_id - (Optional) The external ID to use when assuming the role.
• session_name - (Optional) The session name to use when assuming the role.
• workspace_key_prefix - (Optional) The prefix applied to the state path inside the bucket. This is only relevant when using a non-default workspace. This defaults to "env:"
• skip_credentials_validation - (Optional) Skip the credentials validation via the STS API.
• skip_get_ec2_platforms - (Optional) Skip getting the supported EC2 platforms.
• skip_requesting_account_id - (Optional) Skip requesting the account ID.
• skip_metadata_api_check - (Optional) Skip the AWS Metadata API check.