Introduction

SPRT::CrossStack::Executor helps in deploying CrossAccount/CrossRegional CloudFormation stacks.

In comparison to CloudFormation StackSets, it offers the following additional functionalities:

• Retrieving CloudFormation Outputs inside the "master" CloudFormation.
• Use these Outputs as input for other Resources and configure follow-up Resources accordingly.
• Start installations of different CloudFormation stacks from one single "master" CloudFormation stack.

In comparison to CloudFormation nested Stacks, it offers the following additional functionalities:

• The solution works Cross-Region and
• Cross-Account

Some real world examples include:

• Creation of VPC inside AWS accounts and attaching them to a centralized AWS Transit Gateway.
• Collecting Route53 RecordSet entries for different accounts.
• Creation of SCPs with Accept for only well known ResourceIds from the CloudFormation stack leveraging CrossStack's deployments.

Usage

Requirements

CrossStack is always assuming another role. Please find a quickstart role to deploy inside samples/cross-account-access-role.yml

Syntax

Type: SPRT::CrossStack::Executor
Properties:
  AccountId: String
  AssumeRoleName: String
  AssumeRolePath: String
  CfnCapabilities:
  - Array
  CfnParameters:
    StackParameters
  CfnStackName: String
  CfnTemplate: String
  CfnTemplateUrl: String
  LogLevel: Number
  Region: String

StackParameters Object

ParameterKey1: ParamterValue1
...
ParameterKeyN: ParameterValueN

Properties

AccountId

Defines the AWS Account ID where to deploy the defined CloudFormation template.

Required: Yes

Type: String

Pattern: \d{12}

Update allowed: No

AssumeRoleName

Role name to assume for CrossStack's installations in different AWS accounts.

Required: Yes

Type: String

Update allowed: Yes

AssumeRolePath

Role path to assume for CrossStack's installations in different AWS accounts.

Required: No

Default: /

Type: String

Update allowed: Yes

CfnCapabilities:

Capabilities for Stack to create/update.

Required: No

Default: []

Type: List

Possible values: All known CloudFormation capabilities (CAPABILITY_IAM, CAPABILITY_NAMED_IAM, CAPABILITY_AUTO_EXPAND)

Update allowed: No

CfnParameters

Parameters for CloudFormation stack.

Required: No

Default: {}

Type: Object

Update allowed: Yes

CfnStackName

CloudFormation Stack name for CrossStack's installation.

Required: Yes

Type: String

Update allowed: No

CfnTemplate

CloudFormation Stack template for CrossStack's installation. You must include either CfnTemplateUrl or CfnTemplateBody in a Stack, but you cannot use both.

Required: No

Type: String

Update allowed: Yes

CfnTemplateUrl

CloudFormation Stack template S3 url for CrossStack's installation. You must include either CfnTemplateUrl or CfnTemplateBody in a Stack, but you cannot use both.

Required: No

Type: String

Update allowed: Yes

LogLevel

Internal logging level for CrossStack's CloudWatch logs. Mostly used for debugging purposes.

Required: No

Default: 30

Type: Number

Allowed values: One of Python's defined Logging Levels.

Update allowed: Yes

Region

Defines the AWS Region where to deploy the defined CloudFormation template.

Required: Yes

Type: String

Possible values: One of AWS service endpoints

Update allowed: No

Return values

Ref

Nothing

Fn::GetAtt

CfnStackId

Internal ID of CrossStackResource.

Example: teststack-123456789012-eu-central-1

CfnStackOutput1, ..., CfnStackOutput9

Up to 9 variables can be retrieved from CrossStack installations.

Example: SomeVariableValueFromCrossStackExecution

Examples

Create an S3 bucket

The following example creates and S3 bucket on another AWS account and region. The output variables are catched inside the execution stack and can be used for additional purposes.

Resources:
  TestResource:
    Type: SPRT::CrossStack::Executor
    Properties:
      AccountId: 123456789012
      Region: eu-central-1
      AssumeRoleName: sprt-crossstack-role
      LogLevel: 10
      CfnCapabilities:
      - CAPABILITY_NAMED_IAM
      CfnStackName: my-first-test-stack
      CfnParameters:
        CreatedByTag: CrossStackExecutor
      CfnTemplate: |
        AWSTemplateFormatVersion: 2010-09-09
        Parameters:
          CreatedByTag:
            Type: String
        Resources:
          S3Resource:
            Type: AWS::S3::Bucket
            Properties:
              BucketName: !Sub "some-bucket-name-${AWS::AccountId}-${AWS::Region}"
              Tags:
              - Key: CreatedBy
                Value: !Ref CreatedByTag
        Outputs:
          S3BucketArn:
            Value: !GetAtt S3Resource.Arn

Outputs:
  ExampleOutput:
    Description: Example output for S3 Bucket ARN from child execution
    Value: !GetAtt TestResource.CfnStackOutput1

Development

Setup environment

Pre-requisites:

• Development was done via Cloud9 environment on an Amazon Linux system
• Initial setup followed the steps from github's cloudformation-cli README

Full Resource Provider update and deployment of s3-example:

$ cfn generate
$ cfn validate
$ cfn submit --set-default
$ aws cloudformation deploy --template-file samples/s3-example.yml --stack-name crossstack-resource-provider-test

Debugging and feature enhancement

• First of all: Take care to set Parameter LogLevel: 10, as it adds helpful information about processed handlers and parameters.
• Resource handlers are separated into different files for better readability. They can be found inside src/sprt_crossstack_executor/sub_handlers/*

Q&A

Q: Are all CloudFormation Create/Update Stack parameters supported?
A: Only a subset is implemented right now. Nevertheless, it's easy to add additional ones inside the handler functionalities.

Q: Why are there only nine predefined Output variables from CrossStack's execution?
A: CloudFormation resource provider doesn't allow for dynamic output variables so far. Therefore these predefined set of variables acts as a workaround.

Q: How is this resource tested?
A: Unfortunately the Python contract tests aren't running as of now (@see github issue #112). Therefore tests were done with the provided example deployment samples/s3-examples.yml.

Q: What does the name SPRT stand for?
A: That's an easy one: Super Peculiar Resource Type.