Build Status Gem Version

Overview

Tfctl is a small Terraform wrapper for working with multi-account AWS infrastructures where new accounts may be created dynamically and on-demand.

Discovers accounts by reading the AWS Organizations API and can assign Terraform resources to accounts based on the organization hierarchy. Resources can be assigned globally, based on organization unit or individual accounts. It supports nested OU hierarchies.

Tfctl was originally developed to integrate Terraform with AWS Landing Zone and Control Tower but should work with most other ways of managing accounts in AWS Organizations.

Features

  • Discovers AWS accounts automatically.

  • Automatically generates Terraform account configuration.

  • Parallel execution across multiple accounts.

  • Hierarchical configuration based on AWS Organization units structure.

  • Supports per account configuration overrides for handling exceptions.

  • Supports nested organization units.

  • Terraform state tracking in S3 and locking in DynamoDB.

  • Account targeting by OU path regular expressions.

  • Automatic role assumption in target accounts.

  • Works with CI/CD pipelines.

Requirements

  • Terraform >= 0.12

  • Ruby >= 2.3

  • Accounts managed in AWS Organizations (by Landing Zone, Control Tower, some other means)

Installation

To install the latest release from RubyGems run:

gem install tfctl

Alternatively you can build and install from this repo with:

make install

Docs

Running tfctl

tfctl should be run from the root of the project directory. It will generate Terraform configuration in .tfctl/.

Anatomy of a tfctl command:

tfctl -c CONFIG_FILE TARGET_OPTIONS -- TERRAFORM_COMMAND

  • -c specifies which tfctl config file to use (usually in conf/)

  • TARGET_OPTIONS specifies which accounts to target. This could be an individual account, a group of accounts in an organizational unit or all accounts.

  • TERRAFORM_COMMAND will be passed to terraform along with any options. See Terraform commands for details.

Note
 You must have your AWS credentials configured before running tfctl or run it using an AWS credentials helper such as aws-vault.

Example commands

Show help:

tfctl -h

Show merged configuration:

tfctl -c conf/example.yaml -s

List all discovered accounts:

tfctl -c conf/example.yaml --all -l
Tip
 This can be narrowed down using targeting options and is a good way to test what accounts match.

Run Terraform init across all accounts:

tfctl -c conf/example.yaml --all -- init

Run plan in test OU accounts:

tfctl -c conf/example.yaml -o test -- plan

Run plan in live accounts assuming that live is a child OU in multiple organization units:

tfctl -c conf/example.yaml -o '.*/live' -- plan

Run plan in an individual account:

tfctl -c conf/example.yaml -a example-account - plan

Run apply in all accounts:

tfctl -c conf/example.yaml --all -- apply

Run destroy in test OU accounts:

tfctl -c conf/example.yaml -o test -- destroy -auto-approve

Don’t buffer the output:

tfctl -c conf/example.yaml -a example-account -u -- plan

This will show output in real time. Usually output is buffered and displayed after Terraform command finishes to make it more readable when running across multiple accounts in parallel.