tfctl

// Settings: :idprefix: :idseparator: - ifndef::env-github[:icons: font] ifdef::env-github,env-browser[] :toc: macro :toclevels: 1 endif::[] ifdef::env-github[] :branch: master :status: :outfilesuffix: .adoc :!toc-title: :caution-caption: :fire: :important-caption: :exclamation: :note-caption: :paperclip: :tip-caption: :bulb: :warning-caption: :warning: endif::[]

= tfctl

image:https://github.com/scalefactory/tfctl/actions/workflows/linter.yml/badge.svg["Linter", link="https://github.com/scalefactory/tfctl/actions/workflows/linter.yml"] image:https://github.com/scalefactory/tfctl/actions/workflows/test.yml/badge.svg["Tests", link="https://github.com/scalefactory/tfctl/actions/workflows/test.yml"] image:https://badge.fury.io/rb/tfctl.svg["Gem Version", link="https://badge.fury.io/rb/tfctl"] image:https://img.shields.io/badge/terraform-0.12-blue.svg["Terraform 0.12", link="https://img.shields.io/badge/terraform-0.12-blue"]

toc::[]

== Overview

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 https://aws.amazon.com/solutions/aws-landing-zone/[AWS Landing Zone] and https://aws.amazon.com/controltower/[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.29
• Ruby >= 2.5
• Accounts managed in AWS Organizations (by Landing Zone, Control Tower, some other means)

== Installation

To install the latest release from RubyGems run:

[source,shell]

gem install tfctl

Alternatively, you can build and install from this repo with:

[source,shell]

make install

== Documentation

• https://github.com/scalefactory/tfctl/tree/master/docs/control_tower.adoc[Control Tower quick start guide]
• https://github.com/scalefactory/tfctl/tree/master/docs/project_layout.adoc[Project layout]
• https://github.com/scalefactory/tfctl/tree/master/docs/configuration.adoc[Configuration]
• https://github.com/scalefactory/tfctl/tree/master/docs/iam_permissions.adoc[IAM permissions]
• https://github.com/scalefactory/tfctl/tree/master/docs/creating_a_profile.adoc[Creating a profile]

== Running tfctl

You 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:

[source,shell]

tfctl -c CONFIG_FILE TARGET_OPTIONS -- TERRAFORM_COMMAND

• -c specifies which tfctl config file to use (defaults to tfctl.yaml in current working directory if not set)
• 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 https://www.terraform.io/docs/commands/index.html[Terraform commands] for details.

NOTE: You must have your AWS credentials configured before you run tfctl, or run it using an AWS credentials helper such as https://github.com/99designs/aws-vault[aws-vault].

=== Example commands

Show help:

[source,shell]

tfctl -h

Show merged configuration:

[source,shell]

tfctl -s

List all discovered accounts:

[source,shell]

tfctl --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:

[source,shell]

tfctl --all -- init

Plan Terraform across all accounts in the test OU:

[source,shell]

tfctl -o test -- plan

Plan Terraform in live accounts, assuming that live is a child OU in multiple organization units:

[source,shell]

tfctl -o '.*/live' -- plan

Run a plan for an individual account:

[source,shell]

tfctl -a example-account - plan

Apply Terraform changes across all accounts:

[source,shell]

tfctl --all -- apply

Destroy Terraform-managed resources in all the test OU accounts:

[source,shell]

tfctl -o test -- destroy -auto-approve

Don't buffer the output:

[source,shell]

tfctl -a example-account -u -- plan

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

== Project status

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.