Cleanup and expansion of the S3 remote state documentation (#9708)
This commit is contained in:
James Turnbull
Paul Stack
parent
46e9c56fa3
commit
0dfc7a19c7
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue