2017-02-15 19:47:30 +01:00
|
|
|
---
|
2017-02-15 21:19:38 +01:00
|
|
|
layout: "backend-types"
|
|
|
|
page_title: "Backend Type: s3"
|
|
|
|
sidebar_current: "docs-backends-types-standard-s3"
|
2017-02-15 19:47:30 +01:00
|
|
|
description: |-
|
2017-02-15 21:19:38 +01:00
|
|
|
Terraform can store state remotely in S3 and lock that state with DynamoDB.
|
2017-02-15 19:47:30 +01:00
|
|
|
---
|
|
|
|
|
|
|
|
# S3
|
|
|
|
|
2017-02-15 21:19:38 +01:00
|
|
|
**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/).
|
2017-07-28 21:06:00 +02:00
|
|
|
This backend also supports state locking and consistency checking via
|
|
|
|
[Dynamo DB](https://aws.amazon.com/dynamodb/), which can be enabled by setting
|
|
|
|
the `dynamodb_table` field to an existing DynamoDB table name.
|
2017-02-15 19:47:30 +01:00
|
|
|
|
|
|
|
~> **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.
|
|
|
|
|
2017-02-15 21:19:38 +01:00
|
|
|
## Example Configuration
|
2017-02-15 19:47:30 +01:00
|
|
|
|
2017-04-05 17:29:27 +02:00
|
|
|
```hcl
|
2017-02-15 21:19:38 +01:00
|
|
|
terraform {
|
|
|
|
backend "s3" {
|
|
|
|
bucket = "mybucket"
|
|
|
|
key = "path/to/my/key"
|
|
|
|
region = "us-east-1"
|
|
|
|
}
|
|
|
|
}
|
2017-02-15 19:47:30 +01:00
|
|
|
```
|
|
|
|
|
2017-02-15 21:19:38 +01:00
|
|
|
This assumes we have a bucket created called `mybucket`. The
|
|
|
|
Terraform state is written to the key `path/to/my/key`.
|
2017-02-15 19:47:30 +01:00
|
|
|
|
2017-02-15 21:19:38 +01:00
|
|
|
Note that for the access credentials we recommend using a
|
|
|
|
[partial configuration](/docs/backends/config.html).
|
2017-02-15 19:47:30 +01:00
|
|
|
|
|
|
|
## 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).
|
|
|
|
|
2017-04-05 17:29:27 +02:00
|
|
|
```hcl
|
2017-05-28 08:41:38 +02:00
|
|
|
data "terraform_remote_state" "network" {
|
2017-04-05 17:29:27 +02:00
|
|
|
backend = "s3"
|
|
|
|
config {
|
|
|
|
bucket = "terraform-state-prod"
|
|
|
|
key = "network/terraform.tfstate"
|
|
|
|
region = "us-east-1"
|
|
|
|
}
|
2017-02-15 19:47:30 +01:00
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
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.
|
2017-07-28 21:06:00 +02:00
|
|
|
* `key` - (Required) The path to the state file inside the bucket. When using
|
|
|
|
a non-default [workspace](/docs/state/workspaces.html), the state path will
|
|
|
|
be `/workspace_key_prefix/workspace_name/key`
|
2017-02-15 19:47:30 +01:00
|
|
|
* `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.
|
2017-05-31 00:11:38 +02:00
|
|
|
* `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.
|
2017-02-15 19:47:30 +01:00
|
|
|
* `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.
|
2017-05-31 00:11:38 +02:00
|
|
|
* `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.
|
2017-06-22 19:50:02 +02:00
|
|
|
* `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:"
|
2017-07-14 13:08:47 +02:00
|
|
|
* `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.
|