terraform/website/source/docs/state/remote/s3.html.md

layout	page_title	sidebar_current	description
remotestate	Remote State Backend: s3	docs-state-remote-s3	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.

-> 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 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 of the state file
• acl - 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.