Mapping and StackSets


The mappings section of a CloudFormation template matches a key to a corresponding set of named values. For example, if you want to set values based on a region, you can create a mapping that uses the AWS region name as a key and contains the values you want to specify depending on the region where the template is deployed. This may be particularly useful when deploying AMIs globally where you must deploy a different AMI ID per region due to disaster recovery or security considerations that differ across geographic regions.


AWS CloudFormation StackSets extend the functionality of stacks by enabling you to create, update, or delete stacks across multiple accounts and regions with a single operation. Using an administrator account, you define and manage an AWS CloudFormation template, and use the template as the basis for provisioning stacks into selected target accounts across specified regions. For example, you can easily establish a global AWS CloudTrail or AWS Config policy across multiple accounts with a single StackSet operation. You can also use StackSets to deploy resources in a single account across multiple regions.

In this lab, we will deploy a CloudFormation template that provisions an EC2 instance with a simple webserver to verify proper deployment across multiple regions. We will use mappings to properly deploy the proper Amazon Linux 2 AMI for the selected region while using StackSets to configure which AWS regions will deploy this template.

For the sake of simplicity, we will be utilizing one account as both the administrator and execution role, but you can utilize StackSets across multiple accounts. Please review the Prerequisites: Granting Permissions for Stack Set Operations page for additional information on how to properly configure the two roles required to deploy StackSets across multiple accounts.

Deploy the IAM permissions StackSet

First we will deploy a single stack (not a complete StackSet) to our test account.

This template deploys IAM resources, which are global. Attempts to deploy this same stack to multiple regions by way of a StackSet would fail with an error.

  1. Download the CloudFormation template from this link - you will need it momentarily:
    File name Purpose Download
    mapping_stacksets_iam.yml Creates the CloudFormation stack Download the template
  2. Copy your AWS account number from the top-right dropdown in the console (located next to the AWS region).
  3. Navigate to the CloudFormation console and then click on Create stack.
  4. Select Upload a template to Amazon S3 and upload the CloudFormation template you downloaded, and then click Next.
  5. Give your CloudFormation stack a descriptive name such as mapping-stacksets-iam.
  6. Specify the Account ID of your AWS account that you obtained earlier and click Next.
  7. Review any desired tags and additional options and click Next.
  8. Click the checkbox next to ‘I acknowledge that AWS CloudFormation might create IAM resources with custom names.’ and then click Create.
  9. Click the refresh button to see that the two nested CloudFormation templates were successfully deployed into your account.
  10. Do not delete these nested stacks until the end of the next session as they are the permissions necessary to deploy a StackSet in your account.

Review the IAM permissions template

Examine the CloudFormation template to see that it is a simple nested CloudFormation template that will call two AWS-provided YAML files to provision IAM roles within your account. These are both AWS-managed example templates that you can freely download and further explore.

AWSTemplateFormatVersion: '2010-09-09'
Description: This CloudFormation StackSet deploys two AWS provided CloudFormation templates that add Administrator and Execution Roles required to use AWSCloudFormationStackSetAdministrationRole
    Type: AWS::CloudFormation::Stack
      TimeoutInMinutes: '3'
    Type: AWS::CloudFormation::Stack
      TimeoutInMinutes: '3'
        AdministratorAccountId : !Ref 'AccountID'
      Type: String
      Description: Your AWS Account ID
      MaxLength: 12
      MinLength: 12

Explore example StackSets

  1. Navigate to the CloudFormation console and from the CloudFormation drop-down, select StackSets.
  2. Click Create StackSet.
  3. Examine the AWS-provided CloudFormation sample templates to get an idea of what configuration operations are possible with StackSets:

View the example StackSets

Deploy StackSet with Mapping

This template will deploy resources into the default VPC in each selected region. Please select regions where there is still a default VPC

Now we will create an actual StackSet - though only in this single account. The mechanism is identical whether we deploy to the same account and region, or to multiple accounts and regions.

  1. Download the CloudFormation template from this link:
    File name Purpose Download
    mapping_stacksets_ec2.yml Creates the CloudFormation stack Download the template
  2. In the CloudFormation console, StacksSets, then Create StackSet.
  3. Click Upload a template file, then upload the template you just downloaded, and then click Next.
  4. Give the StackSet a name (such as mapping-stacksets-ec2), and enter a CIDR range that makes sense (or leave as the default, but only if you understand the risk of leaving an EC2 instance’s web server open to the entire Internet).

    Exposing these services publicly without full understanding is not recommended outside of a lab environment.

    This next page may appear slightly different if you are using an AWS account that is a part of an exising AWS Organization. If your page presents a choice between Service-managed permissions and Self-service permissions, please select the latter.

  5. On the Configure StackSet options screen click Next.
  6. In the Set deployment options page, ensure that Deploy stacks in accounts is selected. Paste your current AWS account number inti the Account numbers field, and then select ONLY your current region in the Specify regions dialog. Then click Next. Set your StackSet options
  7. Refresh the page in few moments to see the resulting StackSet, and note that it is now present as a stack in the same region (with a non-deterministic stack name prefixed with StackSet-)

Explore the mapping

Opening the StackSet template, notice the mapping component of this template that will deploy the proper Amazon Linux 2 AMI based on the region where the template is deployed.

# Mapping of Amazon Linux 2 AMI IDs in every AWS Region
# When deploying a StackSet, the template will automatically deploy the proper AMI in each selected region
    AMI: ami-04681a1dbd79675a5
    AMI: ami-0cf31d971a3ca20d6
    AMI: ami-0782017a917e973e7
    AMI: ami-6cd6f714
    AMI: ami-00b6a8a2bd28daf19
    AMI: ami-00f7ef6bf92e8f916
    AMI: ami-012566705322e9a8e
    AMI: ami-01da99628f381e50a
    AMI: ami-00e17d1165b9dd3ec
    AMI: ami-08847abae18baa040
    AMI: ami-ce1b96aa
    AMI: ami-0f5dbc86dd9cbf7a8
    AMI: ami-0bdb1d6c15a40392c
    AMI: ami-e1768386
    AMI: ami-06340c8c12baa6a09
    AMI: ami-0ad7b0031d41ed4b9

Delete the StackSet

  1. Navigate back to the region where you deployed the StackSet and return to the StackSet console. StackSets are deployed globally but reside only in the region where they were initially deployed.
  2. Click the StackSet name.
  3. Click Manage StackSet.
  4. Click Delete Stacks and then click Next.
  5. Enter your AWS account ID into the “Delete stacks from account” input.
  6. Click Add all to select all regions for deletion and then scroll down to click Next.
  7. Click Delete Stacks.
  8. Refresh this page and note that the DELETE operation is running. Allow approximately 5 minutes for this operation to complete across all regions and then navigate to the StackSets console. The operation is finished when there are no regions present under the Stacks section.
  9. Select the StackSet. Under actions, select Delete StackSet and then click Yes, Delete. If you receive a “Failed to delete StackSet” error, please allow more time for the underlying stacks to be deleted.
  10. Return to the CloudFormation Stacks console and delete the parent mapping-stacksets-iam (or similar) template that you deployed in the first step of this lab. Be sure to select the parent Stack, not the “NESTED” stacks.