Automate account creation and resource provisioning for AWS GovCloud(US), using AWS Service Catalog, AWS Organizations, and AWS Lambda

Public and private sector customers are now often working to automate their account creation and operations into the AWS GovCloud (US) Regions. These customers use the AWS GovCloud (US) Regions to access FedRamp certified services and ITAR-governed datasets for multiple accounts. Managing this type of multi-account enterprise footprint with AWS Organizations helps reduce operational costs and overhead. At the same time, AWS Organizations helps you provide governance to meet strict compliance regulation.

If you’ve worked on AWS GovCloud (US), you know that accounts are always mapped to another account in the commercial Region. In this post, I show how to use an account vending machine to create your commercial and AWS GovCloud (US) pair accounts in a single operation. I also show how to set up an AWS Service Catalog product that allows you to quickly bootstrap your new AWS GovCloud (US) deployment with governed, standardized solutions.

AWS Organizations works differently in the AWS GovCloud (US) Region, as compared to the commercial Regions. For a deep dive, please refer the blog post on AWS Organizations in the AWS GovCloud (US) Regions for central governance and management of AWS accounts. This guide contains a detailed description of the account vending machine used to provision AWS accounts with custom configurations in the AWS GovCloud (US) Region.

Prerequisites

• Existing AWS Organization in the commercial AWS account that forms the pair for the AWS GovCloud (US) Region. Refer to the documentation.
• The account you deploy this in must meet the requirements to vend AWS GovCloud (US) accounts and use the API. Refer to the documentation.
• Each Region you want to use this solution in should have its own Amazon Simple Storage Service (Amazon S3) bucket. That bucket should contain the AWS CloudFormation template and AWS Lambda function zip files.

Overview

The account vending machine process for AWS GovCloud (US) works in two separate sequential steps.

1. Creating the AWS GovCloud (US) account from the commercial Region’s master AWS account

You will use the commercial master account in AWS Organizations to call the CreateGovCloudAccount API.

This API request performs the following actions:

• Two new AWS accounts, one in the commercial organization and another in the AWS GovCloud (US) Region.
• A role (OrganizationAccountAccess) is automatically created in the new commercial account that creates a trust relationship with your commercial organization master account.
• A role (OrganizationAccountAccess) is automatically created in the AWS GovCloud (US) account that creates a trust relationship with your AWS GovCloud (US) organization master account.

In order to call the CreateGovCloudAccount API consistently, create an AWS Service Catalog product in the commercial organization master account. This standardizes the creation of the new accounts. You will use an AWS CloudFormation template to set up this AWS Service Catalog product in the commercial master account. The outputs of the AWS Service Catalog product provide the account IDs of the newly created accounts in the commercial and the AWS GovCloud (US) Regions.

2. Bootstrapping the newly created AWS GovCloud (US) account

The newly created AWS GovCloud (US) account from the step 1 contains a role (OrganizationAccountAccess) in the AWS GovCloud (US) account. That role allows the AWS GovCloud (US) organization master account to log into the newly created account.

To prepare the new AWS GovCloud (US) account for your end users, the following actions need to occur:

• Invite the newly created AWS GovCloud (US) account to the AWS GovCloud(US) Organization.
• Accept the invite from the new account in AWS GovCloud (US).
• Bootstrap the account with baseline infrastructure.

To achieve those actions, you will create an AWS Service Catalog product to bootstrap the new AWS GovCloud (US) account. This is a one-time setup. To set up the AWS GovCloud (US) Region’s master AWS account with this product, you will:

• Run an AWS CloudFormation template in that account.
• This CloudFormation template sets up an AWS Service Catalog product that helps bootstrap newly created AWS GovCloud (US) accounts.

Once the initial set up is complete, you will use the Account Bootstrap product to bootstrap any newly created AWS GovCloud(US) accounts. This product performs the following actions:

• takes the newly created AWS GovCloud (US) account ID as input.
• starts an automation to create an AWS Organizations invite from the master.
• accepts the invite from the new account.
• bootstraps the new account with baseline infrastructure you defined.

To summarize, you will launch the AWS Service Catalog bootstrap product once you have the account ID of the new AWS GovCloud (US) account from step one.

Walkthrough

A) In the commercial Region, set up the account vending machine (AVM)

As a part of creating a sample account vending machine from the aws-samples GitHub repository, you will launch a CloudFormation template to set up the account vending machine (AVM) product in AWS Service Catalog in your commercial region master account.

Setting up an Amazon S3 bucket with project files

1. Log in to your AWS account. This must be the master account in AWS Organizations in the commercial Region. You can customize this implementation to work with linked accounts as well, but for the purposes of this exercise, use the master account.
2. Set up an S3 bucket to hold all the artifacts for this implementation.
   1. In the AWS Management Console upper left section, select Services, and then select Amazon S3.
   2. In the Amazon S3 console, select Create S3 bucket. Enter a bucket name of your choice. Choose the commercial Region you plan to use for this exercise. Keep the other default settings, and select Create bucket.
   3. In a new browser tab, open your AWS Management Console again. In the upper left section, select Services, and then select AWS Organizations. On the AWS Organizations page upper right section, select the Settings tab. Note the Organization ID.
   4. On the Amazon S3 console page, in the Buckets section, select the bucket you just created. Select the Permissions tab. Then, select Bucket Policy and enter the following bucket policy. Change the Resource to reflect your Amazon S3 bucket name and the aws:PrincipalOrgId to reflect your Organization ID copied from AWS Organizations in step A.2.3.

      • {
              "Version": "2012-10-17",
               "Statement": [
                   {
                       "Sid": "AllowGetObject",
                       "Effect": "Allow",
                       "Principal": "*",
                       "Action": "s3:GetObject",
                       "Resource": "arn:aws:s3:::<REPLACE WITH YOUR AMAZON S3 BUCKET NAME>/*",
                       "Condition": {
                           "StringEquals": {
                               "aws:PrincipalOrgID": "<REPLACE WITH YOUR AWS ORGANIZATION ID>"
                           }
                       }
                   }
               ]
           }
        

3. Upload all the files from the commercial-side-setup folder of this repository in the Amazon S3 bucket from step A.2.
4. In the Amazon S3 bucket you created, click on the file CommercialAccountSetup.yaml and copy the Object URL from the bottom section of Overview tab.

Launching AWS CloudFormation template

1. In the AWS Management Console upper left section, select Services and then select AWS CloudFormation.
2. Select the Create Stack button, add the Amazon S3 URL you copied in step 4 earlier, and select Next.
3. On the Specify stack details page, enter the following parameters, as shown in the following screenshot:
   • AccountAdministrator: Enter the Amazon Resource Name (ARN) of the Identity and Access Management (IAM) entity (role, user, or group) that performs account creation from AWS Service Catalog. To find the ARN of the role/user/group. (for example, arn:aws:iam::010010011111:role/Administrator), go to the IAM console.
   • StackName: Enter a stack name such as account-vending-machine
   • SourceBucket: Add the name of the Amazon S3 bucket you created in the commercial Region.
   • AccountVendingLambdaZip: Keep the default value for this solution
   • SourceTemplate: Add your Amazon S3 URL for the source template. Select Next.
4. On the Configure stack options page, select Next.
5. On the Review page, check the check box for I acknowledge that AWS CloudFormation might create IAM resources., and select Create Stack. Refer to the following screenshot.
   
6. Once status of the stack changes to CREATE COMPLETE, select the stack and open the Outputs tab to see the output values.
7. In the AWS CloudFormation Outputs section, copy the key and value column contents for AccountVendingLambda. You will use this value during the execution of the account vending machine.

At this point, you have successfully set up the account vending machine in your commercial AWS account.

B) In the AWS GovCloud (US) Region, set up the account bootstrap product

As a part of creating a sample account vending machine from this solution, you will launch a CloudFormation template to set up the account bootstrap product in AWS Service Catalog in your AWS GovCloud (US) region master account.

Setting up an Amazon S3 bucket with project files

1. Log in to your AWS account. This must be the master account in AWS Organizations in the GovCloud Region. You can customize this implementation to work with linked accounts as well, but for the purposes of this exercise, use the master account.
2. Set up an S3 bucket to hold all the artifacts for this implementation.
   1. In the AWS Management Console upper left section, select Services, and then select Amazon S3.
   2. In the Amazon S3 console, select Create S3 bucket. Enter a bucket name of your choice. Choose the commercial Region you plan to use for this exercise. Keep the other default settings, and select Create bucket.
   3. In a new browser tab, open your AWS Management Console again. In the upper left section, select Services, and then select AWS Organizations. On the AWS Organizations page upper right section, select the Settings tab. Note the Organization ID.
   4. On the Amazon S3 console page, in the Buckets section, select the bucket you just created. Select the Permissions tab. Then, select Bucket Policy and enter the following bucket policy. Change the Resource to reflect your Amazon S3 bucket name and the aws:PrincipalOrgId to reflect your Organization ID copied from AWS Organizations in step B.2.3.

      • {
              "Version": "2012-10-17",
               "Statement": [
                   {
                       "Sid": "AllowGetObject",
                       "Effect": "Allow",
                       "Principal": "*",
                       "Action": "s3:GetObject",
                       "Resource": "arn:aws-us-gov:s3:::<REPLACE WITH YOUR AMAZON S3 BUCKET NAME>/*",
                       "Condition": {
                           "StringEquals": {
                               "aws:PrincipalOrgID": "<REPLACE WITH YOUR AWS ORGANIZATION ID>"
                           }
                       }
                   }
               ]
           }
        

3. Upload all the files from the govcloud-side-setup folder of this repository in the Amazon S3 bucket from step B.2.
4. In the Amazon S3 bucket you created, click on the file GovCloudAccountSetup.yaml and copy the Object URL from the bottom section of Overview tab.

Launching AWS CloudFormation template

1. In the AWS Management Console upper left section, select Services and then select AWS CloudFormation.
2. Select the Create Stack button, add the Amazon S3 URL you copied in step 4 earlier, and select Next.
3. On the Specify stack details page, enter the following parameters, as shown in the following screenshot:
   • StackName: Enter a stack name such as account-bootstrap-product
   • AccountAdministrator: o   Enter the ARN of the IAM entity (role or user or group) that you want to perform account bootstrap from AWS Service Catalog. You can go to the IAM console to find the ARN of the role/user/group. (for example, arn:aws-gov-cloud:iam::010010011111:role/Administrator)
   • SourceBucket: Add the name of the Amazon S3 bucket you created in the AWS GovCloud(US) Region.
   • AccountVendingLambdaZip: Keep the default value for this solution
   • SourceTemplate: Add your Amazon S3 URL for the source template. Select Next.
4. On the Configure stack options page, select Next.
5. On the Review page, check the check box for I acknowledge that AWS CloudFormation might create IAM resources., and select Create Stack. Refer to the following screenshot.
   
6. Once status of the stack changes to CREATE COMPLETE, select the stack and open the Outputs tab to see the output values.

At this point, you have successfully set up the account bootstrap product in your AWS GovCloud (US) account.

C) In the commercial Region, launch the account vending machine (AVM) to create new AWS accounts

In this section, you launch the account vending machine product created in AWS Service Catalog. This creates a new AWS account preconfigured with custom settings defined in this exercise. Start in the AWS Management Console. Log in to your AWS account using the IAM role/user/group that you provided for the AccountAdministrator in the setup phase.

1. On the Services menu in the upper left, search for and then choose AWS Service Catalog. You see an AWS Service Catalog product named Account Vending Machine. In the Products list page, select Account Vending Machine, and then select LAUNCH PRODUCT. Refer to the following screenshot.
   
2. On the Product Version page, configure:
   • Name: my-new-account-001b.
   • Select the available version.
   • Select NEXT.
3. On the Parameters page, configure:
   • AccountEmail: Enter a unique email address to be associated with the newly created account.
   • OrganizationalUnitName: Name of the organizational unit (OU) to which the account should be moved into. If the OU you provide doesn’t exist, this solution creates it for you.
   • AccountName: Enter an account name.
   • Select NEXT.
4.  On the TagOptions page, provide your standard set of tagOptions, and/or select NEXT. On the Notifications page, provide your standard notification Amazon SNS topic, and/or select NEXT.
5. On the Review page, review the configuration information, and select LAUNCH. This creates a CloudFormation stack. The initial status of the product is shown as Under change. Wait for about five minutes, and then refresh the screen until the status changes to AVAILABLE. If you want to monitor stack progress, go to the AWS CloudFormation page. To view the step-by-step execution of the account vending Lambda function, go to Amazon CloudWatch.
6. In the Outputs section of AWS Service Catalog, you see the account ID details of both of the newly created accounts. Copy the account ID GovCloudAccountID of the AWS GovCloud (US) account, which you will use in the next step. Refer to the following screenshot.
   

D) In the AWS GovCloud (US) Region, launch the account bootstrap product to bootstrap the newly created AWS GovCloud (US) account

Next, you launch the account bootstrap product created in AWS Service Catalog to create a new AWS account. This account is preconfigured with custom settings defined in this lab. Start by logging in to your AWS GovCloud (US) account using the IAM role/user/group that you provided in the AccountAdministrator in the setup phase.

1. On the Services menu, search for and then choose AWS Service Catalog. You see an AWS Service Catalog product named Account Bootstrap Product. Select Account Bootstrap Product, and then select LAUNCH PRODUCT. If you don’t see this product, make sure you logged in to this account with the role assigned to this AWS Service Catalog product. Read the documentation for more information.
2. On the Product Version page, enter the following details:
   1. Name: my-new-account-001-bootstrap
   2. Select the available version.
   3. Select NEXT.
3. On the Parameters page, configure as follows, and select NEXT. Refer to the following screenshot for the parameter list.
   • AccountId: Enter Account ID of the new account to be bootstrapped in AWS GovCloud (US). Get this from step C.
   • SourceBucket: Enter the name of the source bucket where your baseline CloudFormation template exists.
   • AssumeRoleName: Name of the IAM Role to be assumed in the child account. Keep the default value.
   • StackRegion: Choose the Region where the preconfigured settings should be applied.
   • BaselineTemplate: Keep the default value. You could instead enter the name of the account baseline CloudFormation template.
4. On the TagOptions page, select NEXT. On the Notifications page, select NEXT.
5. On the Review page, review the configuration information, and select LAUNCH. This creates a CloudFormation stack. The initial status of the product is shown as Under change. Wait for about five minutes. Then refresh the screen until the status changes to AVAILABLE. To monitor the stack progress, go to the AWS CloudFormation page. To view the step-by-step execution of the account vending Lambda function, go to Amazon CloudWatch.
6. In the Outputs section of AWS Service Catalog, you see the account details of the bootstrapped account. The LoginURL parameter output helps you log in to the bootstrapped account. Refer to the following screenshot.
   

E) Log in to the bootstrapped AWS GovCloud (US) account for end-user experience

To experience the newly vended account as an end user, log in to the newly vended account using the user created as a part of the setup. You can also explore the account configuration.

View the AWS Service Catalog products available to the end user

1. Log in to your AWS account using the LoginURL provided in the Outputs of the section D. In the AWS GovCloud (US) Region, launch the account bootstrap product to bootstrap the newly created AWS GovCloud (US) account.
2. Make sure you change over to the same Region as the StackRegion in the previous section.
3. On the credentials page, enter the following information:
   • Username: service-catalog-user
   • Password: service-catalog-2020
   • You will be prompted to change your password at first login.
4. On the Services menu in the upper left, search for and then choose AWS Service Catalog. On the products list page, you see the preconfigured AWS Service Catalog products allowed for the current user to provision.

Test if the end user can create a VPC on their own

1. As a part of the account setup, all the default VPCs from every Region have been deleted for this account. You can validate this by going to the Services menu in the upper left and searching for and then choosing VPC.
2. As a security best practice of least privilege, we have restricted the current user to launch AWS Service Catalog products only. You can validate this by trying to create a new VPC from the Amazon VPC console.
   • Select the Launch VPC Wizard button, and then choose Select for VPC with a Single Public Subnet.
   • In the VPC Name field, enter demo, and select Create VPC. You can’t move forward from this page due to lack of permissions.

Use AWS Service Catalog to create a VPC

1. Now, try to perform the same function using AWS Service Catalog. But first, you as the end user need a key pair. Here’s how to get your key pair:
   • In the Amazon EC2 console left navigation menu, under Network & Security, select Key Pairs.
   • Select the Create a key pair button, enter demo in the name field, and select Create.
   • Now, on the Services menu in the upper left, search for and then choose Service Catalog. On the products list page, select Amazon VPC, and select Launch Product.
   • On the Product Version page, configure:
     • Name: my-custom-vpc-001
     • Select the available version.
     • Select NEXT.
2.  On the Parameters page, configure the following:
   • RegionAZ1Name: Choose the Availability Zone for a Region, for example us-gov-west-1.
   • RegionAZ2Name: Choose another Availability Zone for the same Region as above, for example. us-gov-west-1.
   • VPCCIDR: Either keep the default value or change it to a Classless Inter-Domain Routing (CIDR) you want.
   • SubnetAPublicCIDR: Either keep the default value or change it to a CIDR you want.
   • SubnetAPublicCIDR: Either keep the default value or change it to a CIDR you want
   • SubnetAPrivateCIDR: Either keep the default value or change it to a CIDR you want
   • SubnetBPrivateCIDR: Either keep the default value or change it to a CIDR you want
   • CreateBastionInstance: Either keep the default value or change it to true if you want a bastion instance created.
   • BastionInstanceType: Either keep the default value or change it to an instance type you want.
   • EC2KeyPair: Choose the key pair you created in step E.6.
   • BastionSSHCIDR: Enter any value you want, for example, 10.0.0.0/24.
   • LatestAmiId: Either keep the default value or change it to an AMI ID you want.
   • Select NEXT.
3. On the TagOptions page, select NEXT. On the Notifications page, select NEXT.
4. On the Review page, review the configuration information, and select LAUNCH. This creates a CloudFormation stack. The initial status of the product is shown as Under change. Wait for about five minutes, and then refresh the screen until the status changes to AVAILABLE.
5. Validate the Outputs section on AWS Service Catalog screen to see the details of the VPC created.
6. Finally, on the Amazon VPC console, you can verify that a VPC is now created.

In conclusion, you were able to log in as an end user in the newly vended AWS account. You also created AWS resources in a compliant manner using AWS Service Catalog.

Conclusion

This blog post provides a method to enable on-demand creation of AWS accounts that can be customized to the requirements of an organization. Administrators or teams required to provision new accounts can use this approach to standardize the networking configuration and resources. This solution speeds the AWS GovCloud (US) account provisioning process. This best practice deployment solution makes the accounts usable immediately and provides built-in governance.

Authors