github.com/loicalbertin/terraform@v0.6.15-0.20170626182346-8e2583055467/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  `lock_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.