PubSub Topic
Resource Overview
A PubSub Topic represents an Amazon SNS Topic. Amazon Simple Notification Service (SNS) is a service capable of publishing and delivering messages to subscribers and other AWS services. Your recipients are subscribed to a topic, which is where you publish your messages to be appropriately formatted and sent them.
Key Features of Amazon SNS include:
- Push-based message delivery to SNS topic subscribers
- Pay-as-you-go pricing model
- Supports message to multiple endpoint types including IOS and Android
- Works well with AWS Lambda to communicate with other AWS services, manipulate messages, or publish to other SNS topics
- Redundant storage of messages across multiple Availability Zones
A PubSub Topic differs from a Job Queue, in the way that the consuming resource receives a message. A Job Queue requires their consumer resources to poll or "pull" messages from a queue, where as a PubSub Topic "pushes" messages instantaneously to subscribed consumer resources.
Along with its instantaneous messaging, a PubSub Topic is essential when decoupling your application and implementing a Pub/Sub message pattern. A resource produces a message which gets published to your PubSub Topic and consumed by any subscribers. Each subscriber specifies the protocol and end-point for these notifications to be sent.
Event Subscription
Event subscription wires (solid line) visualize and configure event subscription integrations between two resources.
The following resources can be subscribed to a PubSub Topic:
- Function
Service Discovery
Service discovery wires (dashed line) provide compute resources (Function, Edge Function, Docker Task) with the permissions and environment variables required to perform actions using cloud resources within the stack. This resource is on the receiving end of a service discovery wire originating from compute resources.
The following compute resources can use a service discovery wire to access a PubSub Topic resource:
- Function
Configurable Properties
Display Name
Human readable name for this resource that is displayed on the Stackery Dashboard and Stackery CLI output.
Logical ID
The unique identifier used to reference this resource in the stack template. Defining a custom Logical ID is recommended, as it allows you to quickly identify a resource and any associated sub-resources when working with your stack in AWS, or anywhere outside of the Stackery Dashboard. As a project grows, it becomes useful in quickly spotting this resource in template.yaml or while viewing a stack in Template View mode.
The Logical ID of all sub-resources associated with this Topic will be prefixed with this value.
The identifier you provide must only contain alphanumeric characters (A-Za-z0-9) and be unique within the stack.
Default Logical ID Example: Topic2
IMPORTANT : AWS uses the Logical ID of each resource to coordinate and apply updates to the stack when deployed. On any update of a resource's logical ID (or any modification that results in one), CloudFormation will delete the currently deployed resource and create a new one in it's place when the updated stack is deployed.
Use Existing SNS Topic
When enabled, this feature provides you with a field to specify the Amazon Resource Name (ARN) of an existing SNS Topic to reference in your application.
You may reference an environment parameter in order to conditionally reference existing infrastructure based on environment.
IAM Permissions
When connected by a service discovery wire (dashed wire), a Function or Docker Task will add the following IAM policy to its role and gain permission to access this resource.
SNSPublishMessagePolicy
Grants a Function or Docker Task permission to publish a message to a PubSub Topic within the stack or an existing SNS Topic outside of the current stack.
Environment Variables
When connected by a service discovery wire (dashed wire), a Function or Docker Task will automatically populate and reference the following environment variables in order to interact with this resource.
TOPIC_NAME
The Logical ID of the PubSub Topic resource.
Example: Topic2
TOPIC_ARN
The Amazon Resource Name of the SNS Topic.
Example: arn:aws:sns:us-east-1:123456789012:mystack-Topic2
Stackery Code Samples
Example AWS SDK call using the environment variables discussed above. Code samples available for all supported runtimes.
Publish to a Topic
// Load AWS SDK and create a new SNS object
const AWS = require("aws-sdk");
const sns = new AWS.SNS();
exports.handler = async message => {
const notification = "Hello All! \n We've made quite a few changes to our product...";
// Construct parameters for the publish call
const params = {
Message: notification,
Subject: "Weekly Newsletter",
TopicArn: process.env.TOPIC_ARN // supplied by Function service-discovery wire
};
await sns.publish(params).promise();
console.log(params + 'published to ' + process.env.TOPIC_ARN);
}
import boto3
import os
# Create an SNS client
sns = boto3.client('sns')
topic_arn = os.environ['TOPIC_ARN'] # Supplied by Function service-discovery wire
def handler(message, context):
notification = "Hello All! \n We've made quite a few changes to our product...";
# Publish a simple message to the specified SNS topic
response = sns.publish(
TopicArn=topic_arn,
Message=notification,
)
return response
Related AWS Documentation
AWS Documentation: AWS::SNS::Topic