From 0dfc7a19c7110cae9302394b602dad87185ca2c0 Mon Sep 17 00:00:00 2001 From: James Turnbull Date: Sat, 29 Oct 2016 07:11:43 -0400 Subject: [PATCH] Cleanup and expansion of the S3 remote state documentation (#9708) --- website/source/docs/state/remote/s3.html.md | 87 +++++++++++++++------ 1 file changed, 63 insertions(+), 24 deletions(-) diff --git a/website/source/docs/state/remote/s3.html.md b/website/source/docs/state/remote/s3.html.md index d85d6f905..d1a68b162 100644 --- a/website/source/docs/state/remote/s3.html.md +++ b/website/source/docs/state/remote/s3.html.md @@ -6,19 +6,19 @@ description: |- Terraform can store the state remotely, making it easier to version and work with in a team. --- -# s3 +# S3 -Stores the state as a given key in a given bucket on [Amazon S3](https://aws.amazon.com/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 +~> **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. -## Example Usage +## Using S3 for Remote State + +To enable remote state on S3 we run the `terraform remote config` +command like so: ``` terraform remote config \ @@ -28,7 +28,19 @@ terraform remote config \ -backend-config="region=us-east-1" ``` -## Example Referencing +This assumes we have a bucket created called `terraform-state-prod`. The +Terraform state is written to the file `terraform.tfstate` in a folder +called `network`. + +-> **Note:** Passing credentials directly via configuration options will +make them included in cleartext inside the persisted state. Use of +environment variables or a configuration file is recommended. + +## 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). ``` data "terraform_remote_state" "foo" { @@ -41,21 +53,48 @@ data "terraform_remote_state" "foo" { } ``` +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 / environment variables are supported: +The following configuration options or 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_SESSION_TOKEN` environment variable. + * `bucket` - (Required) The name of the S3 bucket. + * `key` - (Required) The path to the 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 access 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_SESSION_TOKEN` environment variable.