How to set up a multi-region, multi-account catalog of company standard AWS Service Catalog products

[Update on 9/30/2020] Note: – Please follow Simplify sharing your AWS Service Catalog portfolios in an AWS Organizations setup to implement a multi-region, multi-account catalog at scale while incorporating recent updates and best practices.

Many AWS customers are adopting AWS Service Catalog to create and manage catalogs of approved IT services for use on AWS. The AWS Service Catalog Hub-and-Spoke model enables organizations to centrally manage IT services they want to distribute to their lines of business (LOBs).

Some of the customers I work with are looking for recommendations on how they can set up a global catalog managed by a centralized team, such as a cloud engineering team for their entire organization. Organizations have a set of generic standardized AWS Service Catalog products, such as a standard way of creating an Amazon EC2 instance or an Amazon RDS database, that they want to distribute to multiple LOBs using multiple AWS accounts in multiple AWS Regions. They understand that they need to set up portfolios in each spoke account in a Hub-and-Spoke model, and they are looking for a way to manage portfolios from a single pane of glass (such as a dashboard for a hub account) instead of having to log in to each spoke AWS account. The single pane of glass for managing hub and spoke portfolios becomes a necessity for larger enterprises that have tens and hundreds of AWS accounts configured as spoke accounts.

This blog explains how you can set up your AWS Service Catalog with the hub account as a single pane of glass to manage your hub and spoke portfolios across multiple AWS accounts and Regions. With this approach, you will be able to centrally create and manage portfolios, products, portfolio access grants, and other operational aspects of the Hub-and-Spoke model for hub-and-spoke portfolios.

Before I get into how it works, let’s first review a few key AWS Service Catalog concepts:

An AWS Service Catalog product is a blueprint for building your AWS resources that you want to make available for deployment on AWS along with the configuration information.
A portfolio is a collection of products, together with the configuration information.
A provisioned product is an AWS CloudFormation stack.
Constraints control the way users can deploy a product. With launch constraints, you can specify a role that the AWS Service Catalog can assume to launch a product.
See Service Catalog reference blueprints for a quick way to set up and configure AWS Service Catalog portfolios and products.

Further reading:

If you are new to AWS Service Catalog see the blog-post that shows you how to control AWS resources available to your users using AWS Service Catalog.
If you have been using AWS Service Catalog and want to understand how the model extends to multiple accounts, see the details on the Hub-and-Spoke model.

AWS CloudFormation StackSets provide an easy way to execute a CloudFormation template in multiple Regions in multiple AWS accounts from a single account. Now that AWS Service Catalog resources can be created using a CloudFormation template, the two capabilities (templates and StackSets) can be combined to create and manage portfolios and products in multiple Regions and AWS accounts.
We recommend using two StackSets, one for setting up a multi-regional hub and another for setting up spoke portfolios. When you execute both StackSets from a single account, you get a single pane of glass for managing your multi-regional hub portfolios as well as spoke portfolios.

Here is the architecture diagram of the catalog set up process.

Architecture diagram

This blog post walks you through the process outlined in the architecture diagram. First, you will set up an identical hub portfolio in two Regions—us-east-1 and us-east-2. To do this, execute a StackSet on the hub account in the us-east-1 and us-east-2 Regions using the sample template provided as part of the blog post in the Set up the Hub portfolio section. The template creates a portfolio, adds a sample product to the portfolio and shares the portfolio with the spoke account.

Next, you will set up spoke portfolios. Execute a StackSet on spoke accounts in the us-east-1 and us-east-2 Regions using the sample template provided as part of the blog in the Distribute the AWS Service Catalog portfolio to spoke accounts section. The template does the following:

Imports the hub portfolio.
Creates a local portfolio.
Adds product imported to the portfolio.
Sets up launch and template constraints.
Grants the end-user access to the local portfolio.

For this use-case let’s assume that you are part of a Cloud Center of Excellence (CCOE) team, and you want to enable your end-users to deploy approved Amazon EMR clusters.

Prerequisites:
To try out the steps outlined in this blog post, you need administrator access to the AWS account that you want to use as a Hub, and you need access to the AWS account you want to use as a Spoke. You will create IAM roles, set up portfolios, and execute StackSets.

Set up the Hub portfolio

The first task is to set up the portfolio in the hub AWS account you intend to use to distribute your products. For this use case, I assume that you want to set up an identical hub portfolio in two AWS Regions and keep both portfolios synchronized. You will use StackSets to set up the hub portfolio in multiple Regions simultaneously.

Here are the steps for setting up a hub account:

Set up CloudFormation StackSet roles for the hub account.
Create a versioned Amazon S3 bucket and then upload the product CloudFormation templates that you want to distribute to the S3 bucket.
Execute CloudFormation StackSets in all Regions in which you want to set up a hub portfolio.
Note:
If you don’t want to set up the hub portfolio in more than one Region, you can do the following:
1. Skip setting up the AWSCloudFormationStackSetExecutionRole in Step 1.
2. Skip Step 3 and instead execute the CloudFormation template identified in Step 3 in the hub account.

Step 1: Set up CloudFormation StackSet roles

In the hub AWS account, you need to create an AWSCloudFormationStackSetAdministrationRole and an AWSCloudFormationStackSetExecutionRole. These roles need to have a trust relationship with the hub AWS account. The CloudFormation service will assume that these roles will execute the CloudFormation template in multiple Regions in the hub account. For information on how to create these roles, see Prerequisites: Granting Permissions for Stack Set Operations.

Step 2: Create an S3 bucket and upload the product CloudFormation templates

Next, in the hub AWS account, create an S3 bucket in which you will maintain CloudFormation templates and then enable versioning on the bucket. You don’t need to make this bucket public. For this exercise, you will create an EMR Cluster product based on the template available in the following GitHub repository. Upload the template to the S3 bucket that you created. You don’t need to make this Amazon S3 object public.

https://raw.githubusercontent.com/aws-samples/aws-service-catalog-reference-architectures/master/emr/sc-emr-ra.json

Note the Amazon S3 path of the template you uploaded. You will specify this as an input when you set up hub portfolios in Step 3.

Step 3: Execute CloudFormation StackSets to set up hub portfolios in the hub AWS account

Note:
If you need to distribute portfolios to a spoke account in a specific Region, you must set up the hub portfolio in that Region, in the hub account.

You need to create a StackSet from the hub account to deploy hub portfolios. For creating the StackSet, please download and use the CloudFormation template available on this link. While running the StackSet, ensure that you specify EMRCFNPath as the full S3 file path of the CloudFormation template that you uploaded in the preceding section. You also need to specify an AWS account ID of the spoke account as SpokeAccountID. Hub portfolios are shared with the account ID specified as SpokeAccountID. Run the StackSet on the hub account in us-east-1 and us-east-2 Regions.

This creates a portfolio with the name “Sample Hub portfolio” in selected Regions. The portfolio will also contain a product, and the portfolio will be shared with the specified spoke account. Open the AWS Management Console, navigate to the CloudFormation console, and note the output of the StackSet that was executed in each Region by the StackSet.

You will update the spoke-setup in the CloudFormation template with these values later.

You have set up your hub portfolio. You can use StackSets to manage portfolios set up in the hub AWS account. You have also created a single pane of glass to manage multiple portfolios set up in multiple Regions in your hub account.

Notes:

To distribute a new product using AWS Service Catalog:
- You need to upload the product’s CloudFormation template in the S3 bucket.
- Modify the CloudFormation you used to set up the hub to also create the new product.
- Distribute the product to local portfolios in the spoke accounts using StackSet.
To add a new version of an existing product:
- Upload the new version’s CloudFormation template to the S3 bucket.
- Modify the hub setup in CloudFormation to create a new product artifact version. The new version will become available in spoke portfolios via the hub-and-spoke model.
To deactivate a product version:
- You can deactivate the version in the hub account’s Regions and it will get deactivated in spoke accounts. You can automate deactivation for identical multi-Region portfolios using the AWS CLI or the AWS SDK for Python (Boto3).

Distribute the AWS Service Catalog portfolio to spoke accounts

To manage local portfolios on spoke accounts centrally, you can use AWS CloudFormation StackSets. Before you use the StackSets from your hub account, you need to ensure that you have appropriate roles set up in the spoke accounts.

Step 1. Set up a StackSet role in the spoke account

In the spoke AWS account, you need to create an AWSCloudFormationStackSetExecutionRole that has a trust relationship with the hub account. For information on how to create this role, see Prerequisites: Granting Permissions for Stack Set Operations.

Next, you can now execute the CloudFormation template to set up the portfolio structure in the spoke AWS account.

Step 2. Set up portfolios on spoke accounts

You will set up local portfolios using StackSets. With StackSets, a single CloudFormation template executes on specified spoke accounts. This means that it needs to be account/Region agnostic. You can incorporate custom account or Region-specific logic inside your template using CloudFormation mappings and conditions.

Notes:

If you have not migrated tags in the spoke account, ensure that you copy/migrate tags before you run StackSet.
If you need to manage multiple groups of accounts that are identical, you can split the spoke setup CloudFormation template into multiple templates. Then you can use multiple StackSets and reduce the complexity of having to use multiple CloudFormation condition elements.
The sample CloudFormation template specified assumes that you have a consistent naming convention for IAM groups/roles in your spoke accounts. If that is not the case, you can use define mappings and use the Fn::FindInMap pseudo function to grant access to the portfolio for each account dynamically.
If you are creating launch roles in spoke accounts using a StackSet, ensure that you do not have hard-coded names for roles.

The sample CloudFormation template creates the following resources:

A sample portfolio with name Sample-Spoke-Portfolio.
Adds a product with the name EMR cluster to the portfolio.
An IAM launch role and associates it with the EMR cluster product.
A template constraint that allows the end user to deploy only a c4.large or an m4.large instance master/core node instance.
Associates the cost-center TagOption with the sample portfolio.
Grants end users access to the portfolio.

Before you execute the template, download the sample spoke StackSet template to your local computer.

Next, open it using a text editor and do the following:

Update appropriate values for cost-center, portfolio-id, and product-id in the Mappings section. Review the Region name used in mappings section. The sample template assumes you are using the us-east-1 and us-east-2 Regions. If you are distributing a portfolio to multiple Regions, modify mappings to include all Regions along with corresponding PortfolioIDs and ProductIDs. Specify the hub’s Region-specific portfolio and the product IDs that you noted earlier.
```
CostCenter:
"UPDATE_SPOKE_ACCOUNT_ID_HERE":
ID: "UPDATE_COST_CENTER_HERE"
PortfolioID:
us-east-1:
"ID": "UPDATE_US-EAST-1-Hub-PORTFOLIO_ID_HERE"
us-east-2:
"ID": "UPDATE_US-EAST-2-Hub-PORTFOLIO_ID_HERE"
EMRProductID:
us-east-1:
"ID": "UPDATE_US-EAST-1-Hub-PRODUCT_ID_HERE"
us-east-2:
"ID": "UPDATE_US-EAST-2-Hub-PRODUCT_ID_HERE"
```
Review/update the PrincipalARN in the AdminPortfolioPrincipalAssociation resource to include the Amazon Resource Name (ARN) format of the IAM user/group/role that will launch this product, and then save the file. The end users must have the AWSServiceCatalogEndUserFullAccess policy associated.
Review AWS Service Catalog and CloudFormation service limits to avoid running into limits during the template execution.

Next, you need to create a StackSet from the hub account to deploy spoke portfolios using the template you modified earlier. While running the StackSet, ensure that you specify the IAMGroupName of end users that exists in all spoke accounts. You also need to specify all spoke account ID, along with appropriate Regions.

Finally, review the portfolio structure deployed and test by deploying an EMR cluster from the local spoke portfolio as an end user.

Now your multi-regional hub and your spokes, are set up. By creating hub-and-spoke portfolios from a StackSet created in a single Region, you now have created a single pane of glass that you can use to manage your portfolios.

Conclusion

AWS Service Catalog enables you to build and distribute catalogs of IT services to your organization. This blog post shows how you can use CloudFormation Service Catalog resource types with StackSets to create a single pane of glass in the hub account to manage your catalogs in spoke accounts.

If you have questions about implementing the solution described in this blog post, you can start a new thread on the AWS Service Catalog Forum or contact AWS Support.

About the Author

Kanchan Waikar is an AWS Marketplace Solutions Architect at Amazon Web Services. She enjoys helping customers build architectures using AWS, AWS Marketplace products, and AWS Service Catalog.

AWS Cloud Operations & Migrations Blog