AWS – Using StackSets to deploy resources to multiple regions

If you have a CloudFormation template that you have authored in order to create resources in a single region, what happens when you want to deploy those same resources into another region, or even another account? You could manually create the stacks, or you could string together a few CLI scripts to do the job for you; but, there’s a better way.

StackSets allow you to deploy a template across multiple regions and accounts, in a way that is fully managed by CloudFormation. 

Getting ready

Before you can use StackSets, you must establish an account to be the administrator account, and then you must create roles in the administrator account and in the target accounts. In this recipe, you will deploy to a second region, rather than a second account, but those roles still must exist.

The roles must have the following names:

  • AWSCloudFormationStackSetAdministrationRole
  • AWSCloudFormationStackSetExecutionRole

Consult the AWS documentation for details on how to create these roles: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-prereqs.html.

You can create a stack with the following YAML, in order to create these roles in your account.

AWSTemplateFormatVersion: '2010-09-09'
Description: Deploys required roles for Stack Sets
Resources:
    AWSCloudFormationStackSetAdministrationRole:
        Type: AWS::CloudFormation::Stack
        Properties:
            TemplateURL: https://s3.amazonaws.com/cloudformation-stackset-sample-templates-us-east-1/AWSCloudFormationStackSetAdministrationRole.yml 
            TimeoutInMinutes: '3'
    AWSCloudFormationStackSetExecutionRole:
        Type: AWS::CloudFormation::Stack
        Properties:
            TemplateURL: https://s3.amazonaws.com/cloudformation-stackset-sample-templates-us-east-1/AWSCloudFormationStackSetExecutionRole.yml 
            TimeoutInMinutes: '3'
            Parameters:
                AdministratorAccountId : !Ref "AWS::AccountId"

Make sure that you take the time to fully understand how these roles work, since misconfiguration can allow the cross-account role to have more privileges than intended.

How to do it…

Follow these steps to launch a stack in multiple regions:

  1. Log in to the AWS console and select the N. Virginia (us-east-1 ) region.
  2. Take note of your account ID in the account dropdown in the menu bar.
  3. If you haven’t completed the previous recipe, do so now, and retain the YAML file on your filesystem. We will use that same template in the following step.
  4. Go to the CloudFormation console, and click StackSets, then Create StackSet.
  5. Upload the template file from the previous recipe.
  6. Give the stack a descriptive name, and choose an operating system:

StackSet details
  1. Click Next, and then select the role that is to be used for the administration of the StackSet:

StackSet options
  1. Click Next. On the following screen, you will configure the deployment options for the StackSet.
  2. Select Deploy stacks in accounts, and paste in your account number.
  1. Under Specify regions, select US East (N. Virginia) and US West (N. California):

StackSet deployment options
  1. Click Next, then Submit. Wait for the StackSet creation to complete.
  2. Go to the Stack instances tab in order to see the instances that were created:

Stack instances
  1. Go to the EC2 console in each region in order to confirm that the EC2 instances were created.
  2. In order to clean up the resources that were created in this recipe, go back to the CloudFormation console, and select the StackSet.
  3. Select Delete stacks from StackSet from the Actions drop-down menu.
  4. Enter the same configuration information as you did in steps 9-10, in order to specify the account and regions from which to delete stacks.
  5. Click Next, then Submit. Wait until the delete operation finishes.
  6. Now that the stacks are deleted, select Delete StackSet from the Actions drop-down menu.

How it works…

StackSet management is done from an administrator account, and stacks within the StackSet are created in target accounts. The target account, as in this recipe, can be the same as the administrator account. A trust relationship must exist between these accounts, since the administrator account needs the right to create resources in the target accounts. CloudFormation assumes the AWSCloudFormationStackSetAdministrationRole role, which gives it permissions to assume the AWSCloudFormationStackSetExecutionRole role in the target accounts. By default, that role allows all administrative actions, so, in a production setting, you should scope the execution role down to only those actions that are needed in order to create your stack instances. In order to make sure only the administrator account can assume the execution role, an explicit trust relationship is established back to the administrative account.

Check out the AWS documentation for a detailed description of the security prerequisites: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-prereqs.html.

There’s more…

Here are a few tips to help you to get the most out of the StackSets feature:

  • When you design templates that will be used to launch stacks across multiple regions and accounts, keep in mind the specific capabilities of each individual region, since not all services are deployed to all regions. And keep naming conflicts in mind when provisioning resources such as IAM roles or S3 buckets. It’s best practice not to give explicit names to resources in templates; rather, you should allow CloudFormation to assign unique names, and then use stack outputs and cross-stack references in order to get the names when you need them.
  • Start small with your StackSets, deploying to one region at a time at first, in order to observe whether or not the stacks are successfully created, before deploying to a large number of regions or accounts.
  • As with stacks themselves, splitting your StackSets into multiple, smaller templates can make administration much easier. Divide and conquer!

See also

  • Chapter 8, AWS Account Security and Identity

Comments are closed.