terraform-aws-backend

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, like a 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.

Multi-Account Usage

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, substituting PARENT_ACCT_ID and PARENT_REGION, CHILD_ACCT_ID, AND EXTERNAL_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.

Cross Account State Management

See Use 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. See this 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=

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

Requirements

Name	Version
terraform	>= 0.14
aws	>= 4.0
local	>= 2.0
random	>= 3.0

Providers

Name	Version
aws	4.28.0
local	2.2.3
random	3.4.1

Modules

No modules.

Resources

Name	Type
aws_dynamodb_table.this	resource
aws_kms_alias.this	resource
aws_kms_key.this	resource
aws_s3_bucket.this	resource
aws_s3_bucket_lifecycle_configuration.this	resource
aws_s3_bucket_logging.this	resource
aws_s3_bucket_ownership_controls.this	resource
aws_s3_bucket_public_access_block.this	resource
aws_s3_bucket_server_side_encryption_configuration.this	resource
aws_s3_bucket_versioning.this	resource
local_file.assumerole_addrole	resource
local_sensitive_file.assumerole_tfassumerole	resource
random_password.external_id	resource
aws_caller_identity.current	data source
aws_iam_policy_document.key	data source
aws_partition.current	data source
aws_region.current	data source

Inputs

Name	Description	Type	Default	Required
assumerole_role_attach_policies	Policy ARNs to attach to role (can be managed or custom but must exist)	list(string)	[ "arn:aws:iam::aws:policy/AdministratorAccess" ]	no
assumerole_role_external_id	External ID to attach to role (this is required, a random ID will be generated if not specified here)	string	null	no
assumerole_role_name	Name of role to create in assumerole template	string	"Terraform"	no
assumerole_stack_name	Name of CloudFormation stack	string	"tf-assumerole"	no
assumerole_template_name	File name of assumerole cloudformation template	string	"assumerole/tfassumerole.cfn.yml"	no
bucket_name	Name of bucket to hold tf state	string	n/a	yes
create_assumerole_template	If true, create a CloudFormation template that can be run against accounts to create an assumable role	bool	false	no
dynamo_locktable_name	Name of lock table for terraform	string	"tf-locktable"	no
dynamodb_kms_key_arn	KMS key arn to enable encryption on dynamodb table. Defaults to alias/aws/dynamodb	string	null	no
dynamodb_point_in_time_recovery	DynamoDB point-in-time recovery.	bool	true	no
dynamodb_server_side_encryption	Bool to enable encryption on dynamodb table	bool	true	no
kms_alias_name	Name of KMS Alias	string	null	no
kms_key_id	ARN for KMS key for all encryption operations (a key will be created if this is not provided)	string	null	no
lifecycle_rules	lifecycle rules to apply to the bucket (set to null to skip lifecycle rules)	list(object( { id = string enabled = bool prefix = string expiration = number noncurrent_version_expiration = number }))	null	no
logging_target_bucket	The name of the bucket that will receive the log objects (logging will be disabled if null)	string	null	no
logging_target_prefix	A key prefix for log objects	string	null	no
tags	Mapping of any extra tags you want added to resources	map(string)	{}	no

Outputs

Name	Description
backend_config_stub	Backend config stub to be used in child account(s)
external_id	External ID attached to IAM role in managed accounts
kms_key_arn	ARN of KMS Key for S3 bucket
provider_config_stub	Provider config stub to be used in child account(s)
s3_bucket_backend	S3 bucket used to store TF state