Implement Account Factory for Terraform (AFT) by using a bootstrap pipeline

Created by Vinicius Elias (AWS) and Edgar Costa Filho (AWS)

Summary

Notice: AWS CodeCommit is no longer available to new customers. Existing customers of AWS CodeCommit can continue to use the service as normal. Learn more

This pattern provides a simple and secure method for deploying AWS Control Tower Account Factory for Terraform (AFT) from the management account of AWS Organizations. The core of the solution is an AWS CloudFormation template that automates the AFT configuration by creating a Terraform pipeline, which is structured to be easily adaptable for initial deployment or subsequent updates.

Security and data integrity are top priorities at AWS, so the Terraform state file, which is a critical component that tracks the state of the managed infrastructure and configurations, is securely stored in an Amazon Simple Storage Service (Amazon S3) bucket. This bucket is configured with several security measures, including server-side encryption and policies to block public access, to help ensure that your Terraform state is safeguarded against unauthorized access and data breaches.

The management account orchestrates and oversees the entire environment, so it is a critical resource in AWS Control Tower. This pattern follows AWS best practices and ensures that the deployment process is not only efficient but also aligns with security and governance standards, to offer a comprehensive, secure, and efficient way to deploy AFT in your AWS environment.

For more information about AFT, see the AWS Control Tower documentation.

Prerequisites and limitations

Prerequisites

Limitations

Product versions

Architecture

Target technology stack

Target architecture

The following diagram illustrates the implementation discussed in this pattern.

The workflow consists of three main tasks: creating the resources, generating the content, and running the pipeline.

Creating the resources

The CloudFormation template that's provided with this pattern creates and sets up all required resources, depending on the parameters you select when you deploy the template. At the minimum, the template creates the following resources:

Additionally, if you set the Generate AFT Files parameter in the CloudFormation template to true, the template creates these additional resources to generate the content:

Generating the content

To generate the AFT bootstrap files and their content, the solution uses a Lambda function and an S3 bucket. The function creates a folder in the bucket, and then creates two files inside the folder: main.tf and backend.tf. The function also processes the provided CloudFormation parameters and populates these files with predefined code, replacing the respective parameter values.

To view the code that's used as a template to generate the files, see the solution's GitHub repository. Basically, the files are generated as follows.

main.tf

module "aft" {
  source = "github.com/aws-ia/terraform-aws-control_tower_account_factory?ref=<aft_version>"

  # Required variables
  ct_management_account_id  = "<ct_management_account_id>"
  log_archive_account_id    = "<log_archive_account_id>"
  audit_account_id          = "<audit_account_id>"
  aft_management_account_id = "<aft_management_account_id>"
  ct_home_region            = "<ct_home_region>"

  # Optional variables
  tf_backend_secondary_region = "<tf_backend_secondary_region>"
  aft_metrics_reporting       = "<false|true>"

  # AFT Feature flags
  aft_feature_cloudtrail_data_events      = "<false|true>"
  aft_feature_enterprise_support          = "<false|true>"
  aft_feature_delete_default_vpcs_enabled = "<false|true>"

  # Terraform variables
  terraform_version      = "<terraform_version>"
  terraform_distribution = "<terraform_distribution>"

}

backend.tf

terraform {
  backend "s3" {
    region = "<aft-main-region>"
    bucket = "<s3-bucket-name>"
    key    = "aft-setup.tfstate"
  }
}

During the CodeCommit repository creation, if you set the Generate AFT Files parameter to true, the template uses the S3 bucket with the generated content as the source of the main branch to automatically populate the repository.

Running the pipeline

After the resources have been created and the bootstrap files have been configured, the pipeline runs. The first stage (Source) fetches the source code from the main branch of the repository, and the second stage (Build) runs the Terraform plan command and generates the results to be reviewed. In the third stage (Approval), the pipeline waits for a manual action to approve or reject the last stage (Deploy). At the last stage, the pipeline runs the Terraform apply command by using the result of the previous Terraform plan command as input. Finally, a cross-account role and the permissions in the management account are used to create the AFT resources in the AFT management account.

Tools

AWS services

Other tools

Code repository

The code for this pattern is available in the GitHub AFT bootstrap pipeline repository.

For the official AFT repository, see AWS Control Tower Account Factory for Terraform in GitHub.

Best practices

When you deploy AFT by using the provided CloudFormation template, we recommend that you follow best practices to help ensure a secure, efficient, and successful implementation. Key guidelines and recommendations for implementing and operating the AFT include the following.

Epics

Troubleshooting

Related resources

To implement this pattern successfully, review the following resources. These resources provide additional information and guidance that can be invaluable in setting up and managing AFT by using AWS CloudFormation.

AWS documentation:

IAM policies and best practices:

Terraform on AWS:

AWS service quotas: