Deploy AWS Control Tower Account Factory for Terraform (AFT) - AWS Control Tower

Deploy AWS Control Tower Account Factory for Terraform (AFT)

This section is for administrators of AWS Control Tower environments who wish to set up Account Factory for Terraform (AFT) in their existing environment. It describes how to set up an Account Factory for Terraform (AFT) environment with a new, dedicated AFT management account.

Note

A Terraform module deploys AFT. This module is available in the AFT repository on GitHub, and the entire AFT repository is considered the module.

We recommend that you refer to the AFT modules on GitHub instead of cloning the AFT repository. This way you can control and consume updates to the modules as they are available.

For details about the latest releases of the AWS Control Tower Account Factory for Terraform (AFT) functionality, see the Releases file for this GitHub repository.

Deployment prerequisites

Before you configure and launch your AFT environment, you must have the following:

Note

By default, AFT uses AWS CodeCommit. For more information, see What is AWS CodeCommit? in the AWS CodeCommit User Guide.

If you'd like to choose a different VCS provider, see Alternatives for version control of source code in AFT.

  • A runtime environment where you can run the Terraform module that installs AFT.

  • AFT feature options. For more information, see Enable feature options.

Configure and launch your AWS Control Tower Account Factory for Terraform

The following steps assume that you're familiar with the Terraform workflow. You can also learn more about deploying AFT by following the Introduction to AFT lab on the AWS Workshop Studio website.

Step 1: Launch your AWS Control Tower landing zone

Complete the steps in Getting started with AWS Control Tower. This is where you create the AWS Control Tower management account and set up your AWS Control Tower landing zone.

Note

Make sure to create a role for the AWS Control Tower management account that has AdministratorAccess credentials. For more information, see the following:

Step 2: Create a new organizational unit for AFT (recommended)

We recommend that you create a separate OU in your AWS organization. This is where you deploy the AFT management account. Create the new OU with your AWS Control Tower management account. For more information, see Create a new OU.

Step 3: Provision the AFT management account

AFT requires that you provision an AWS account dedicated to AFT management operations. The AWS Control Tower management account, which is associated to your AWS Control Tower landing zone, vends the AFT management account. For more information, see Provision accounts with AWS Service Catalog Account Factory.

Note

If you created a separate OU for AFT, make sure to select this OU when you create the AFT management account.

Note

You might wait up to 30 minutes before the AFT management account is fully provisioned.

Step 4: Verify the Terraform environment is available for deployment

This step assumes that you have experience with Terraform and have procedures in place for executing Terraform. For more information, see Command: init on the HashiCorp Developer website.

Note

AFT supports Terraform Version 0.15.x or later.

Step 5: Call the Account Factory for Terraform module to deploy AFT

Call the AFT module with the role that you created for the AWS Control Tower management account that has AdministratorAccess credentials. AWS Control Tower provisions a Terraform module through the AWS Control Tower management account, which establishes all of the infrastructure required to orchestrate AWS Control Tower Account Factory requests.

Note

You can view the AFT module in the AFT repository on GitHub. The entire GitHub repository is considered the AFT module. Refer to the README file for information about the input that's required to run the AFT module and deploy AFT. Alternatively, you can view the AFT module in the Terraform Registry.

If you have pipelines in your environment that are established for managing Terraform, you can integrate the AFT module into your existing workflow. Otherwise, run the AFT module from any environment that's authenticated with the required credentials.

A Terraform state file is generated when you deploy AFT. This artifact describes the state of the resources that Terraform created. If you plan to update the AFT version, make sure to preseve the Terraform state file, or set up a Terraform backend using Amazon S3 and DynamoDB. The AFT module doesn't manage a backend Terraform state.

Note

You're responsible for protecting the Terraform state file. Some input variables might contain sensitive values, such as a private ssh key or Terraform token. Depending on your deployment method, these values can be viewable as plain text in the Terraform state file. For more informaiton, see Sensitive data in State on the HashiCorp website.

Timeout causes deployment to fail. We recommend using AWS Security Token Service (STS) credentials to ensure you have a timeout that's sufficient for a full deployment. The minimum timeout for AWS STS credentials is 60 minutes. For more informaiton, see Temporary security credentials in IAM in the AWS Identity and Access Management User Guide.

Note

You might wait up to 30 minute for AFT to finish deploying through the Terraform module.