--- 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. * `role_arn` - (Optional) The role to be assumed