62 lines
2.4 KiB
Markdown
62 lines
2.4 KiB
Markdown
---
|
|
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/).
|
|
|
|
-> **Note:** Passing credentials directly via config options will
|
|
make them included in cleartext inside the persisted state.
|
|
Use of environment variables or config file is recommended.
|
|
|
|
~> **Warning!** It is highly recommended to 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.
|
|
|
|
## Example Usage
|
|
|
|
```
|
|
terraform remote config \
|
|
-backend=s3 \
|
|
-backend-config="bucket=terraform-state-prod" \
|
|
-backend-config="key=network/terraform.tfstate" \
|
|
-backend-config="region=us-east-1"
|
|
```
|
|
|
|
## Example Referencing
|
|
|
|
```
|
|
resource "terraform_remote_state" "foo" {
|
|
backend = "s3"
|
|
config {
|
|
bucket = "terraform-state-prod"
|
|
key = "network/terraform.tfstate"
|
|
region = "us-east-1"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Configuration variables
|
|
|
|
The following configuration options / environment variables are supported:
|
|
|
|
* `bucket` - (Required) The name of the S3 bucket
|
|
* `key` - (Required) The path where to place/look for 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 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_SECURITY_TOKEN` environment variable.
|