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

Amazon Web Services Feed
How to automate the creation of multiple accounts in AWS Control Tower

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. 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. Creating accounts using AWS Control Tower’s Account Factory is a single-threaded process at this point, customers must allow for the current account creation process to complete before they can begin the next account creation process.

In this post, we demonstrate how you can automate the creation of multiple accounts in AWS Control Tower using a batch account creation process. For example, you can use this solution to create a number of sandbox accounts for your application, or to create multiple accounts a new team. You can execute this batch process overnight or over a weekend, and when you return, your AWS Control Tower accounts are ready for use. 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:

• AWS Control Tower
• AWS Service Catalog
• AWS CloudFormation
• Amazon DynamoDB
• AWS Lambda
• Amazon CloudWatch Events
• Amazon S3
• Amazon SNS (optional)

Solution overview

The following diagram illustrates the batch account creation process.

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 master account in the AWS Region where you launched AWS Control Tower.

Things to know before you get started

AWS Control Tower’s Account Factory can take up to 45 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 at the end of the business day or over a weekend.

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.
4. Upload the input file, sample.csv, to an Amazon S3 bucket, and grant public read access to the object.
5. Note the Object URL of the uploaded object.  It is of the form https://<s3-bucket-name>.s3.<region-name>.amazonaws.com/sample.csv in our example.

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.
2. Verify that page is as shown in the following screenshot. Click Next.
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 URLForInputCSVFile to the object URL of the input file that you previously uploaded to the S3 bucket.  In our example, we set the Amazon S3 URL to https://<s3-bucket-name>.s3.<aws-region>.amazonaws.com/sample.csv, as seen in the following screenshot.
   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.

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

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.

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.

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

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.

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

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

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