tfctl is a small Terraform wrapper for working with multi-account AWS
infrastructures where new accounts may be created dynamically and on-demand.
It discovers accounts by reading the AWS Organizations API, and can assign Terraform resources to multiple accounts based on the organization hierarchy. Resources can be assigned globally, based on organization unit (OU) or to individual accounts. It supports hierarchies of nested OUs, and helps keep your Terraform DRY.
The Scale Factory originally created tfctl to integrate Terraform with AWS Landing Zone and Control Tower but should work with most other ways of managing accounts in AWS Organizations.
-
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.
-
Terraform >= 0.12.29
-
Ruby >= 2.5
-
Accounts managed in AWS Organizations (by Landing Zone, Control Tower, some other means)
To install the latest release from RubyGems run:
gem install tfctlAlternatively, you can build and install from this repo with:
make installYou should run tfctl from the root of your project directory. It will generate
Terraform configuration in .tfctl/ (add this to your .gitignore).
Anatomy of a tfctl command:
tfctl -c CONFIG_FILE TARGET_OPTIONS -- TERRAFORM_COMMAND-
-cspecifies which tfctl config file to use (defaults totfctl.yamlin current working directory if not set) -
TARGET_OPTIONSspecifies which accounts to target. This could be an individual account, a group of accounts in an organizational unit or all accounts. -
TERRAFORM_COMMANDwill be passed toterraformalong with any options. See Terraform commands for details.
|
📎
|
You must have your AWS credentials configured before you run tfctl, or run
it using an AWS credentials helper such as
aws-vault.
|
Show help:
tfctl -hShow merged configuration:
tfctl -sList all discovered accounts:
tfctl --all -l|
💡
|
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 --all -- initPlan Terraform across all accounts in the test OU:
tfctl -o test -- planPlan Terraform in live accounts, assuming that live is a child OU in multiple
organization units:
tfctl -o '.*/live' -- planRun a plan for an individual account:
tfctl -a example-account - planApply Terraform changes across all accounts:
tfctl --all -- applyDestroy Terraform-managed resources in all the test OU accounts:
tfctl -o test -- destroy -auto-approveDon’t buffer the output:
tfctl -a example-account -u -- planThis will show output in real time. Usually output is buffered and displayed after the Terraform command finishes, to make it more readable when running across multiple accounts in parallel.
tfctl is an open source project published by The Scale Factory.
We currently consider this project to be maintained but we don’t actively develop new features. We keep it security patched and ready for use in production environments.
We’ll take a look at any issues or PRs you open and get back to you as soon as we can. We don’t offer any formal SLA, but we’ll be checking on this project periodically.
If your issue is urgent, you can flag it as such, and we’ll attempt to triage appropriately, but we have paying customers who also have demands on our time. If your business depends on this project and you have an urgent problem, then you can talk to our sales team about paying us to support you.