Repository files navigation

Creates an S3 bucket and DynamoDB table for managing Terraform state. Note that when bootstrapping a new environment, it is typically easier to use a separate method for creating the bucket and lock table, likea CloudFormation Stack. This module is intended to create a backend in an AWS account that is already Terraform-managed. This is useful to store the state for other accounts externally.

This module will create a CloudFormation stack and an optional wrapper script to deploy it. This stack is suitable to run in any account that will store its Terraform state in the bucket created by this module. It creates an IAM role with the AdministratorAccess policy attached and with an External ID which can then be assumed by terraform to create resources in the child account(s).

Breaking Changes

Previous versions of this module had support for cross-account management in a way that proved awkward for many uses cases and made it more difficult than it should've to fully secure the tfstate between accounts. Version 4.x and later eliminates support for this and refocuses the module on using centralized tfstate buckets with cross-account role assumption for execution of terraform. As a result, many variable names have changed and functionality has been dropped. Upgrade to this version at your own peril.

These instructions assume two AWS accounts; a "Parent" account which holds the terraform state and IAM users, and a "Child" account.

1. In the parent account create this module. The below code is a serving suggestion.

module "backend" {  source  = "rhythmictech/backend/aws"  version = "4.1.0"  bucket_name                = "${local.account_id}-${var.region}-terraform-state"  create_assumerole_template = true  logging_target_bucket      = module.s3logging-bucket.s3_bucket_name  logging_target_prefix      = "${local.account_id}-${var.region}-tf-state"  tags                       = module.tags.tags_no_name}

It will create a folder with a shell script and a CloudFormation stack in it.

2. Log into the child account and run the shell script,assumerole/addrole.sh. This will create a CloudFormation stack in that child account.

3. In the terraform code for the child account create the provider and backend sections like below, substitutingPARENT_ACCT_ID andPARENT_REGION,CHILD_ACCT_ID, ANDEXTERNAL_ID.

terraform backend config:

bucket         = "PARENT_ACCT_ID-PARENT_REGION-terraform-state"dynamodb_table = "tf-locktable"key            = "account.tfstate"region         = "PARENT_REGION"

provider config:

provider "aws" {  assume_role {    role_arn     = "arn:aws:iam::CHILD_ACCT_ID:role/Terraform"    session_name = "terraform-network"    external_id  = "EXTERNAL_ID"  }}

4. Log in to the master account and run terraform using this backend and provider config. The state will be stored in the parent account but terraform will assume the child account role.

SeeUse AssumeRole to Provision AWS Resources Across Accounts for more information on this pattern.

This module is not intended to hold the state for the account in which it is created. If the account itself is also Terraform managed, it is recommended to create a separate bucket for its own state manually or via a different IaC method (e.g., CloudFormation) to avoid the chicken-and-egg problem. Seethis CloudFormation template to create terraform backend for this or any other single account.

You can test the ability to assume a role in the child account by logging in with the parent account and running this

export $(printf "AWS_ACCESS_KEY_ID=%s AWS_SECRET_ACCESS_KEY=%s AWS_SESSION_TOKEN=%s" \$(aws sts assume-role \--external-id EXTERNAL_ID \--role-arn arn:aws:iam::CHILD_ACCT_ID:role/Terraform \--role-session-name testme \--query "Credentials.[AccessKeyId,SecretAccessKey,SessionToken]" \--output text))%  AWS_SECURITY_TOKEN=

Thenaws sts get-caller-identity should reveal you to be in the child account.

No modules.

[
  "arn:aws:iam::aws:policy/AdministratorAccess"
]

list(object(
    {
      id                            = string
      enabled                       = bool
      prefix                        = string
      expiration                    = number
      noncurrent_version_expiration = number
  }))