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

---
layout: "remotestate"
page_title: "Remote State Backend: s3"
sidebar_current: "docs-state-remote-s3"
description: |-
  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](https://aws.amazon.com/s3/).

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

## 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](/docs/providers/terraform/d/remote_state.html).

```
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](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.
 * `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.