github.com/spirius/terraform@v0.10.0-beta2.0.20170714185654-87b2c0cf8fea/website/docs/backends/types/s3.html.md (about) 1 --- 2 layout: "backend-types" 3 page_title: "Backend Type: s3" 4 sidebar_current: "docs-backends-types-standard-s3" 5 description: |- 6 Terraform can store state remotely in S3 and lock that state with DynamoDB. 7 --- 8 9 # S3 10 11 **Kind: Standard (with locking via DynamoDB)** 12 13 Stores the state as a given key in a given bucket on 14 [Amazon S3](https://aws.amazon.com/s3/). 15 This backend also supports state locking via 16 [Dynamo DB](https://aws.amazon.com/dynamodb/). Enable locking by setting the 17 `dynamodb_table` key to a Dynamo DB table to use for the locks. 18 19 ~> **Warning!** It is highly recommended that you enable 20 [Bucket Versioning](http://docs.aws.amazon.com/AmazonS3/latest/UG/enable-bucket-versioning.html) 21 on the S3 bucket to allow for state recovery in the case of accidental deletions and human error. 22 23 ## Example Configuration 24 25 ```hcl 26 terraform { 27 backend "s3" { 28 bucket = "mybucket" 29 key = "path/to/my/key" 30 region = "us-east-1" 31 } 32 } 33 ``` 34 35 This assumes we have a bucket created called `mybucket`. The 36 Terraform state is written to the key `path/to/my/key`. 37 38 Note that for the access credentials we recommend using a 39 [partial configuration](/docs/backends/config.html). 40 41 ## Using the S3 remote state 42 43 To make use of the S3 remote state we can use the 44 [`terraform_remote_state` data 45 source](/docs/providers/terraform/d/remote_state.html). 46 47 ```hcl 48 data "terraform_remote_state" "network" { 49 backend = "s3" 50 config { 51 bucket = "terraform-state-prod" 52 key = "network/terraform.tfstate" 53 region = "us-east-1" 54 } 55 } 56 ``` 57 58 The `terraform_remote_state` data source will return all of the root outputs 59 defined in the referenced remote state, an example output might look like: 60 61 ``` 62 data.terraform_remote_state.network: 63 id = 2016-10-29 01:57:59.780010914 +0000 UTC 64 addresses.# = 2 65 addresses.0 = 52.207.220.222 66 addresses.1 = 54.196.78.166 67 backend = s3 68 config.% = 3 69 config.bucket = terraform-state-prod 70 config.key = network/terraform.tfstate 71 config.region = us-east-1 72 elb_address = web-elb-790251200.us-east-1.elb.amazonaws.com 73 public_subnet_id = subnet-1e05dd33 74 ``` 75 76 ## Configuration variables 77 78 The following configuration options or environment variables are supported: 79 80 * `bucket` - (Required) The name of the S3 bucket. 81 * `key` - (Required) The path to the state file inside the bucket. 82 * `region` / `AWS_DEFAULT_REGION` - (Optional) The region of the S3 83 bucket. 84 * `endpoint` / `AWS_S3_ENDPOINT` - (Optional) A custom endpoint for the 85 S3 API. 86 * `encrypt` - (Optional) Whether to enable [server side 87 encryption](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingServerSideEncryption.html) 88 of the state file. 89 * `acl` - [Canned 90 ACL](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl) 91 to be applied to the state file. 92 * `access_key` / `AWS_ACCESS_KEY_ID` - (Optional) AWS access key. 93 * `secret_key` / `AWS_SECRET_ACCESS_KEY` - (Optional) AWS secret access key. 94 * `kms_key_id` - (Optional) The ARN of a KMS Key to use for encrypting 95 the state. 96 * `lock_table` - (Optional, Deprecated) Use `dynamodb_table` instead. 97 * `dynamodb_table` - (Optional) The name of a DynamoDB table to use for state 98 locking and consistency. The table must have a primary key named LockID. If 99 not present, locking will be disabled. 100 * `profile` - (Optional) This is the AWS profile name as set in the 101 shared credentials file. 102 * `shared_credentials_file` - (Optional) This is the path to the 103 shared credentials file. If this is not set and a profile is specified, 104 `~/.aws/credentials` will be used. 105 * `token` - (Optional) Use this to set an MFA token. It can also be 106 sourced from the `AWS_SESSION_TOKEN` environment variable. 107 * `role_arn` - (Optional) The role to be assumed. 108 * `assume_role_policy` - (Optional) The permissions applied when assuming a role. 109 * `external_id` - (Optional) The external ID to use when assuming the role. 110 * `session_name` - (Optional) The session name to use when assuming the role. 111 * `workspace_key_prefix` - (Optional) The prefix applied to the state path 112 inside the bucket. This is only relevant when using a non-default workspace. 113 This defaults to "env:"