Skip to content

Setup Terraform remote state in the S3 backend (with DynamoDB locking) for AWS

License

Notifications You must be signed in to change notification settings

aryounce/terraform-aws-bootstrap

Repository files navigation

Terraform Bootstrap for AWS

Quickly get started with the Terraform S3 backend.

These Terraform and CloudFormation templates solve the chicken-and-egg problem with the Terraform S3 backend by setting up all of the resources needed in the "administrative AWS account" so that Terraform may be used safely in a multi-account, multi-user setup. This includes:

  • A S3 bucket for Terraform state.
  • A DynamoDB table for managing the state lock.
  • A pre-built IAM policy that can be used for enabling access to the S3 backend.
  • SSM Parameter Store values to make the S3 bucket name and DynamoDB table name accessible to other automation.

Setup

Either the Terraform or CloudFormation template may be used as they are equivalent. Using appropriate AWS credentials for your "administrative" account, do the following:

Via Terraform

Use the Terraform template when you wish to manage everything in your AWS acccount(s) with Terraform. Additional steps are required to import the local state created when setting up the S3 backend.

For full instructions, see: S3 backend setup via Terraform

terraform apply

Via CloudFormation

Use the CloudFormation template when either you don't intend to manage your AWS resources with Terraform, but wish to store your state in S3, or you wish to keep your backend resources outside of your Terraform state.

For full instructions, see: S3 backend setup via CloudFormation

aws cloudformation deploy \
  --stack-name terraform-bootstrap \
  --template-file terraform-bootstrap.yaml \
  --capabilities CAPABILITY_NAMED_IAM

Usage

After setup you must create your Terraform configuration utilizing the newly initialized backend for state.

The included generate-backend-hcl.sh script will pull the needed values from your administrative AWS account and generate a proper configuration for you. See the header comment of the script for more information.

Terraform Backend Configuration Example

terraform {
  backend "s3" {
    region         = "us-east-1"
    profile        = "admin-acct-profile"
    bucket         = "terraform-bootstrap-bucket-XXXXXXXXXXXXX"
    key            = "terraform-state/terraform.tfstate"
    dynamodb_table = "terraform-locking"
  }
}

IAM Authentication for Multiple AWS Accounts

When using the S3 backend to store state for managing multiple AWS accounts you will need to authenticate against both the administrative AWS account with background credentials (from the CLI profile specified in the backend configuration) and the AWS account you wish to manage with foreground credentials. Depending on your preferred approach the configuration of the S3 backend may need to be modified.

Related Reading