Skip to content

Creates a backend S3 bucket and DynamoDB table for managing Terraform state in external accounts

License

Notifications You must be signed in to change notification settings

rhythmictech/terraform-aws-backend

Repository files navigation

terraform-aws-backend

tflint tfsec yamllint misspell pre-commit-check follow on Twitter

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).

visualization

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.

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

  2. 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"
  }
}
  1. 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