Subscribe multiple email endpoints to an SNS topic by using a custom resource

Created by Ricardo Morais (AWS)

Environment: Production

Technologies: DevOps

AWS services: Amazon SNS; AWS CloudFormation; AWS Lambda

Summary

Note, August 2022: AWS CloudFormation now supports the subscription of multiple resources through the AWS::SNS::Topic object and its Subscription attribute.

This pattern describes how to subscribe multiple email addresses to receive notifications from an Amazon Simple Notification Service (Amazon SNS) topic. It uses an AWS Lambda function as a custom resource in an AWS CloudFormation template. The Lambda function is associated with an input parameter that specifies the email endpoints for the SNS topic.

Currently, you can use the AWS CloudFormation template objects AWS::SNS::Topic and AWS::SNS::Subscription to subscribe single endpoints to SNS topics. To subscribe multiple endpoints, you have to invoke the object multiple times. By using the Lambda function as a custom resource, you can subscribe multiple endpoints through an input parameter. You can use this Lambda function as a custom resource in any AWS CloudFormation template. 

Prerequisites and limitations

Prerequisites

• An active AWS account.

• An AWS profile configured in your local environment with an access key and secret key. You can also run this code from AWS Cloud9.

• Permissions for the following:

  • AWS Identity and Access Management (IAM) role and policy

  • AWS Lambda function

  • Amazon Simple Storage Service (Amazon S3) for uploading the Lambda function

  • Amazon SNS topic and policy

  • AWS CloudFormation stacks

Limitations

• The code supports Linux and macOS workstations.

Product versions

• AWS Command Line Interface (AWS CLI) version 2 or later.

Architecture

Target technology stack

• AWS CloudFormation

• Amazon SNS

• AWS Lambda

Tools

Tools

• AWS CLI version 2

Code

The attachment includes the following files:

• Lambda function: lambda_function.py

• AWS CloudFormation template: template.yaml

• Two parameter files to handle multiple or single email endpoint subscriptions: parameters-multiple-values.json (used as the default) and parameters-one-value.json

To deploy the stack, you can use either parameter file. To specify multiple email endpoints: 

./deploy.sh -p <YOUR_AWS_PROFILE_NAME> -r <YOUR_AWS_PROFILE_REGION>

To specify a single email endpoint:

./deploy.sh -p <YOUR_AWS_PROFILE_NAME> -r <YOUR_AWS_PROFILE_REGION> -f parameters-one-value.json

Epics

Option 1 - Deploy an SNS topic with one email subscription

Task	Description	Skills required
Configure the email endpoint for SNS topic subscriptions.	Edit the file parameters-one-value.json (attached), and change the value of the pSNSNotificationsEmail parameter to reflect the email address you want to use, such as [e-mail].
Deploy the AWS CloudFormation stack that creates the resources and subscription.	Run the deploy.sh command with your AWS profile name, AWS Region, and the parameters-one-value.json file. ./deploy.sh -p <YOUR_AWS_PROFILE_NAME> -r <YOUR_AWS_PROFILE_REGION> -f parameters-one-value.json	IAM role with proper permissions

Option 2 - Deploy an SNS topic with two or more email subscriptions

Task	Description	Skills required
Configure the email endpoints for SNS topic subscriptions.	Edit the file parameters-multiple-values.json (attached), and change the value of the pSNSNotificationsEmail parameter to reflect the email addresses you want to use, separated by commas, as follows: [e-mail], [e-mail].
Deploy the AWS CloudFormation stack that creates the resources and subscription.	Run the deploy.sh command with your AWS profile name and AWS Region. You don't have to specify the parameters-multiple-values.json file because it's used by default. ./deploy.sh -p <YOUR_AWS_PROFILE_NAME> -r <YOUR_AWS_PROFILE_REGION>	IAM role with proper permissions

Option 3 - Deploy an SNS topic through an AWS CloudFormation template

Task	Description	Skills required
Create an SNS topic.	Create an SNS topic through an AWS CloudFormation template, without specifying subscription endpoints in the AWS::SNS::Topic template object. You can use template.yaml in the attachment as a starting point.	IAM role with proper permissions
Create an SNS topic policy.	Create an SNS topic policy in the AWS CloudFormation template.	IAM role with proper permissions
Subscribe the email endpoints list to the SNS topic.	Based on the list of email endpoints (one or more), subscribe the endpoints to the SNS topic you created.	IAM role with proper permissions

Related resources

References

• AWS CloudFormation custom resources (AWS documentation)

• AWS CloudFormation custom resource creation with Python, AWS Lambda, and crhelper (blog post)

Required tools

• AWS CLI version 2

Attachments

To access additional content that is associated with this document, unzip the following file: attachment.zip