AWS Cloud Operations Blog

How to automate the creation of multiple accounts in AWS Control Tower

Last updated 24 Feb 2022 to support submission of 300+ account entries per each deployment.

Last updated 17 Nov 2021 to handle the changes to Account Factory inputs parameters with Nested OU support.

Last updated 25 JUL 2021 to pass account details from local S3 bucket.

Many customers that we work with are creating and provisioning new accounts using AWS Control Tower. AWS Control Tower is an AWS managed service that automates the creation of a well-architected multi-account AWS environment. AWS Control Tower’s Account Factory is currently a single-threaded process, and customers must allow for the current account creation process to complete before they can begin the next account creation process. You can execute this batch account creation solution overnight or over a weekend, and when you return, your AWS Control Tower accounts are ready for use. This simplifies new account provisioning and centralized compliance for your AWS Organizations. With AWS Control Tower, builders can provision new AWS accounts that conform to your company-wide policies in a few clicks.

In this post, we demonstrate how you can automate the creation of multiple accounts in AWS Control Tower. You can use this solution to create a number of sandbox accounts for your application, or to create multiple accounts a new team. The batch account creation process is also designed to handle some common mistakes that you may make when creating new accounts in AWS Control Tower.

This solution uses the following AWS services:

Solution overview

The following diagram illustrates the batch account creation process.

Solution architecture for Batch account creation using AWS Control Tower

Steps 1–2 describe the initiation, while steps 3–8 describe the core of the batch account creation process.

Step-1: Log in as the AWS Control Tower administrator, and deploy an AWS CloudFormation stack. You also upload an input file that contains the details of the accounts that you want to create in AWS Control Tower. These details are listed later in this post.

Step-2: When the stack is successfully deployed, it performs the following actions to set up the batch process.

  1. Step-2a: It creates an Amazon DynamoDB table. This table tracks the account creation status.
  2. Step-2b, 2c: It creates an AWS Lambda function, NewAccountHandlerLambda. This function validates the input file entries (see Step-1), and uploads the validated input file entries to the DynamoDB table.
  3. Step-2d: It creates an Amazon CloudWatch Events rule that to detect the AWS Control Tower CreateManagedAccount lifecycle event.
  4. Step-2e: It creates and triggers a Lambda function, CreateManagedAccountLambda. This function initiates the batch account creation process.

Step-3: The CreateManagedAccountLambda queries the DynamoDB table to get the details of the next account to be created.  If there is another account to be created, then the batch account creation process moves on to Step-4, else it completes.

Step-4: The CreateManagedAccountLambda launches the AWS Control Tower Account factory product in AWS Service Catalog to create and provision a new account.

Step-5: After Account Factory has completed the account creation workflow, it generates the CreateManagedAccount lifecycle event, and the event log states if the workflow SUCCEEDED or FAILED.

Step-6: The CloudWatch Events rule detects the CreateManagedAccount lifecycle event, and triggers the CreateManagedAccountLambda function.

Step-7: The CreateManagedAccountLambda function updates the DynamoDB table with the results of the account creation workflow.  If the account was successfully created, it updates the input file entry in the DynamoDB table with the account ID, else it updates the entry in the table with the appropriate failure or error reason.

Step-8: When the DynamoDB table is updated, the DynamoDB stream triggers the CreateManagedAccountLambda function, and steps 3–7 are repeated.

Prerequisites

The following prerequisites are necessary for this solution:

  1. You have an AWS Control Tower landing zone deployed in your account.  You can refer to the AWS Control Tower User Guide on getting started.
  2. To implement this solution, you must log in as the AWS Control Tower administrator into the organization management account in the AWS Region where you launched AWS Control Tower.
  3. You can provide the input file (example: `sample.csv`) only during launch of this solution.  Updating the input file or updating the cloudformation stack with new input file will be ignored.
  4. If you like to create new batch of AWS Accounts, deploy this solution again with new input file.

Things to know before you get started

AWS Control Tower’s Account Factory can take up to 35 minutes to create and provision a new account.  During this time, you are unable to use AWS Control Tower to perform actions such as creating an organizational unit (OU) or enabling a guardrail on an OU. We recommend that you consider running this solution at a time period when you do not anticipate using AWS Control Tower’s features extensively, such as during off-hours or over a weekend.

The source code for this solution is available here.

Preparing the list of accounts to be created

  1. Download the input file, sample.csv, to your local drive.
  2. To create a new account using AWS Control Tower’s Account Factory, you need:
    • an account name,
    • a unique email address to associate with the new account,
    • an SSO email address,
    • an SSO user name, and
    • the name of the registered OU where the new account is to be placed.
  3. In our example, as shown in the following screenshot, we include these details for the three new accounts that we want to create. Sample Input file
  4. Create an Amazon S3 bucket in the organization management account. Note the S3 bucket name, you will use it while launching the solution.
  5. Upload the input file, sample.csv, to the Amazon S3 bucket created above.

Optional: Creating a CloudWatch Events rule to receive email notifications

This is an optional step. You can refer to a previous post, Using lifecycle events to track AWS Control Tower actions and trigger automated workflows, that describes how you can create a CloudWatch Events rule and be notified by email after Account Factory has completed an account creation workflow.

Launching the batch account creation process

  1. Launch the CloudFormation stack, BatchAccountCreation.yaml. This link redirects you to us-east-1 region, change it to your AWS Control Tower home region.
  2. Verify that page is as shown in the following screenshot. Click Next. Launch CloudFormation stack - Step-1 - Create stack
  3. On the Specify stack details page,
    1. Specify the Stack name.  In our example, we set the stack name to BatchAccountCreation, as shown in the following screenshot.
    2. Under Parameters,
      • Set the S3BucketName to the bucket you created previous.
      • Update S3KeyName if you renamed the sample.csv earlier.
    3. Click Next.
  4. Continue to the Review page.  Verify the details under Step 1: Specify template and Step 2: Specify stack details.  Acknowledge that IAM resources might be created, and choose Create Stack.

The batch account creation process is now underway.  You can check the progress on the CloudFormation console, or on the Activities page on the AWS Control Tower dashboard, as shown in the following screenshot.

Activities page on AWS Control Tower dashboard

After the accounts have been created, you can view the accounts on the AWS Control Tower dashboard, as shown in the following screenshot.

List of accounts on AWS Control Tower dashboard

If you created a CloudWatch Events rule to receive an email notification after Account Factory completes an account creation workflow, then you can receive the CreateManagedAccount lifecycle event logs in your email, as seen in the following screenshot.

Lifecycle event published to SNS notification

Finally, you can go to the DynamoDB console to view the details of the BatchAccountCreation-NewAccountDetailsTable-* table.  This table is created by the CloudFormation stack, BatchAccountCreation. As seen in the following screenshot, the table gives the list of accounts created along with their account IDs, and the parent OU of the new account.  Although not shown in the following screenshot, the table can also list the account email address, the SSO email address, and the SSO User’s First and Last names. You can visit this table anytime to know the current status of the batch account creation process because it is updated after the completion of every individual account creation process.

DynamoDB Table listingHandling common sources of errors

Customers tell us that some common mistakes or errors they may encounter when creating new accounts include

  1. submitting an account email address that is already associated with another AWS account, and
  2. placing the account in an OU that is not registered with AWS Control Tower.

As described previously in the post, the NewAccountHandlerLambda Lambda function validates the input parameters in the sample.csv input file.  For example, the Lambda function checks if the designated OU for each input entry is registered with your AWS Control Tower -governed organization; if it is not, then the DynamoDB entry for that input entry is marked as INVALID.

If Account Factory encounters an error and does not complete its workflow, then the solution reports both the error message and the status returned by Account Factory.

To demonstrate this solution’s error handling capabilities, create a second input file, sample-err.csv, from the original sample.csv file, as shown in the following screenshot.

Sample Error file

In sample-err.csv, introduce the following sources of account creation errors.

  1. The account email address for the Test-account-4 is the same as the email address associated with Test-account-1.
  2. Test-OU-3, the designated OU for the Test-account-6, does not exist.

The input entry for Test-account-5 does not contain any errors.

Next, as described previously, upload sample-err.csv to the S3 bucket, and grant public read access to the object.  Run the CloudFormation stack, BatchAccountCreation.yaml, set the stack name to BatchAccountCreation-Err, and use the object URL for the uploaded sample-err.csv object.

After the batch account creation process has completed, you can return to the DynamoDB console to view the new table, BatchAccountCreation-Err-NewAccountDetailsTable-*, as seen in the following screenshot.   As expected, Account Factory successfully creates Test-account-5, but it fails to create Test-account-4 and Test-account-5.

DynamoDB Table listingYou can export this table to a file, BatchAccountCreation-Err-Results.csv, as seen in the following screenshot, to study the error messages returned by Account Factory.  For Test-Account-4, Account Factory reported that the account email address was already associated with another AWS account; thus, this account was not created. For Test-account-6, the NewAccountHandlerLambda Lambda function detected that Test-OU-3 is not a valid OU in this organization, and so, it did not launch the account creation process.

DynamoDB Table saved to Excel spreadsheet

Cleanup steps

  1. You can go to the AWS CloudFormation console, and delete the CloudFormation stack that you deployed to run the batch account creation process.  This also deletes other resources, such as the two Lambda functions, CloudWatch Event rules, and the DynamoDB table, that the CloudFormation stack created as part of this solution.
  2. You can export the final status of the account creation to either a .csv file or retain it in the CloudWatch Logs for your future reference.
  3. If you created a CloudWatch event rule to receive email notifications whenever Account Factory finishes an account creation workflow, then you can delete the event rule from the CloudWatch Events console.
  4. You can go to the provisioned products page of the AWS Service Catalog console to view all accounts created by Account Factory, irrespective of whether they were created successfully or not.

Conclusion

In this post, we show how to automate the creation of multiple accounts in AWS Control Tower.  When the batch account creation process completes, you can download the results to a report. We also demonstrated how the architecture can handle errors during the account creation process.

Additionally, you can use Customizations for AWS Control Tower to apply custom templates and policies to your accounts. With custom templates, you can deploy new resources or apply additional custom policies to the new accounts. The solution also integrates with AWS Control Tower lifecycle events to ensure that resource deployments stay in sync with your landing zone.

About the Authors

author-kishore Kishore Vinjam is a Partner Solutions Architect focusing on AWS Service Catalog, AWS Control Tower, and AWS Marketplace. He is passionate about working in cloud technologies, and working with customers and building solutions for them. When not working, he likes to spend time with his family, hike, and play volleyball and ping-pong.
author-raja Raja Mani is a Solution Architect supporting AWS partners. He is interested in Serverless development, DevOps, Containers, Big Data, Security and Machine Learning. He is helping AWS partners to architect the enterprise-grade AWS Solutions for their customers.
author-kalyan Kalyan Ghatak is a Senior Technical Product Manager on the AWS Control Tower team. Kalyan loves working with AWS customers on solving difficult problems and helping them build on AWS. Outside of work, he enjoys listening to classical music and reading classics.