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

---
layout: "backend-types"
page_title: "Backend Type: s3"
sidebar_current: "docs-backends-types-standard-s3"
description: |-
  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](https://aws.amazon.com/s3/).
This backend also supports state locking via
[Dynamo DB](https://aws.amazon.com/dynamodb/). Enable locking by setting the
`dynamodb_table` key to a Dynamo DB table to use for the locks.

~> **Warning!** It is highly recommended that you enable
[Bucket Versioning](http://docs.aws.amazon.com/AmazonS3/latest/UG/enable-bucket-versioning.html)
on the S3 bucket to allow for state recovery in the case of accidental deletions and human error.

## Example Configuration

```hcl
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](/docs/backends/config.html).

## Using the S3 remote state

To make use of the S3 remote state we can use the
[`terraform_remote_state` data
source](/docs/providers/terraform/d/remote_state.html).

```hcl
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.
 * `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](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingServerSideEncryption.html)
   of the state file.
 * `acl` - [Canned
   ACL](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#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:"