github.com/ves/terraform@v0.8.0-beta2/website/source/docs/state/remote/s3.html.md (about)

     1  ---
     2  layout: "remotestate"
     3  page_title: "Remote State Backend: s3"
     4  sidebar_current: "docs-state-remote-s3"
     5  description: |-
     6    Terraform can store the state remotely, making it easier to version and work with in a team.
     7  ---
     8  
     9  # S3
    10  
    11  Stores the state as a given key in a given bucket on [Amazon
    12  S3](https://aws.amazon.com/s3/).
    13  
    14  ~> **Warning!** It is highly recommended that you enable
    15  [Bucket Versioning](http://docs.aws.amazon.com/AmazonS3/latest/UG/enable-bucket-versioning.html)
    16  on the S3 bucket to allow for state recovery in the case of accidental deletions and human error.
    17  
    18  ## Using S3 for Remote State
    19  
    20  To enable remote state on S3 we run the `terraform remote config`
    21  command like so:
    22  
    23  ```
    24  terraform remote config \
    25  	-backend=s3 \
    26  	-backend-config="bucket=terraform-state-prod" \
    27  	-backend-config="key=network/terraform.tfstate" \
    28  	-backend-config="region=us-east-1"
    29  ```
    30  
    31  This assumes we have a bucket created called `terraform-state-prod`. The
    32  Terraform state is written to the file `terraform.tfstate` in a folder
    33  called `network`.
    34  
    35  -> **Note:** Passing credentials directly via configuration options will
    36  make them included in cleartext inside the persisted state. Use of
    37  environment variables or a configuration file is recommended.
    38  
    39  ## Using the S3 remote state
    40  
    41  To make use of the S3 remote state we can use the
    42  [`terraform_remote_state` data
    43  source](/docs/providers/terraform/d/remote_state.html).
    44  
    45  ```
    46  data "terraform_remote_state" "foo" {
    47  	backend = "s3"
    48  	config {
    49  		bucket = "terraform-state-prod"
    50  		key = "network/terraform.tfstate"
    51  		region = "us-east-1"
    52  	}
    53  }
    54  ```
    55  
    56  The `terraform_remote_state` data source will return all of the root outputs
    57  defined in the referenced remote state, an example output might look like:
    58  
    59  ```
    60  data.terraform_remote_state.network:
    61    id = 2016-10-29 01:57:59.780010914 +0000 UTC
    62    addresses.# = 2
    63    addresses.0 = 52.207.220.222
    64    addresses.1 = 54.196.78.166
    65    backend = s3
    66    config.% = 3
    67    config.bucket = terraform-state-prod
    68    config.key = network/terraform.tfstate
    69    config.region = us-east-1
    70    elb_address = web-elb-790251200.us-east-1.elb.amazonaws.com
    71    public_subnet_id = subnet-1e05dd33
    72  ```
    73  
    74  ## Configuration variables
    75  
    76  The following configuration options or environment variables are supported:
    77  
    78   * `bucket` - (Required) The name of the S3 bucket.
    79   * `key` - (Required) The path to the state file inside the bucket.
    80   * `region` / `AWS_DEFAULT_REGION` - (Optional) The region of the S3
    81   bucket.
    82   * `endpoint` / `AWS_S3_ENDPOINT` - (Optional) A custom endpoint for the
    83   S3 API.
    84   * `encrypt` - (Optional) Whether to enable [server side
    85     encryption](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingServerSideEncryption.html)
    86     of the state file.
    87   * `acl` - [Canned
    88     ACL](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl)
    89     to be applied to the state file.
    90   * `access_key` / `AWS_ACCESS_KEY_ID` - (Optional) AWS access key.
    91   * `secret_key` / `AWS_SECRET_ACCESS_KEY` - (Optional) AWS secret access key.
    92   * `kms_key_id` - (Optional) The ARN of a KMS Key to use for encrypting
    93     the state.
    94   * `profile` - (Optional) This is the AWS profile name as set in the
    95     shared credentials file.
    96   * `shared_credentials_file`  - (Optional) This is the path to the
    97     shared credentials file. If this is not set and a profile is specified,
    98     `~/.aws/credentials` will be used.
    99   * `token` - (Optional) Use this to set an MFA token. It can also be
   100     sourced from the `AWS_SESSION_TOKEN` environment variable.