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:

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.

It can take up to 30 minutes to fully provision the AFT management account.

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

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 inputs that are required to run the AFT module and deploy AFT. Alternatively, you can view the AFT module in the Terraform Registry.

The AFT module includes a aft_enable_vpc parameter that specifies if AWS Control Tower provisions account resources within a virtual private cloud (VPC) in the central AFT management account. By default, the parameter is set to true. If you set this parameter to false, AWS Control Tower deploys AFT without the use of a VPC and private networking resources, such as NAT Gateways or VPC endpoints. Disabling aft_enable_vpc may help reduce the operating cost of AFT for some usage patterns.

Note

Re-enabling the aft_enable_vpc parameter (switching the value from false to true) may require you to run the terraform apply command twice in succession.

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.

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 information, see Temporary security credentials in IAM in the AWS Identity and Access Management User Guide.

Note

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

Step 6: Manage the Terraform state file

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 information, see Sensitive data in State on the HashiCorp website.