AWS CDK SNS Subscriptions (v1)

1.204.0 · maintenance · verified Fri Apr 17

This library provides AWS CDK constructs for defining various Amazon SNS subscription types (e.g., SQS, Lambda, Email, SMS). It is part of the AWS Cloud Development Kit (CDK) v1 ecosystem, allowing developers to define cloud infrastructure using familiar programming languages. The CDK project, and its associated modules, follow a rapid release cadence, often with weekly or bi-weekly updates for bug fixes and new features. This entry specifically covers version 1.x of the SNS subscriptions module.

Common errors

```
ModuleNotFoundError: No module named 'aws_cdk.aws_sns_subscriptions'
```
cause The `aws-cdk-aws-sns-subscriptions` PyPI package (for v1) or `aws-cdk-lib` (for v2) is not installed in your environment, or you are trying to use v2 imports without installing `aws-cdk-lib`.

fix For CDK v1: `pip install aws-cdk.aws-sns-subscriptions`. For CDK v2: `pip install aws-cdk-lib constructs`.
```
TypeError: Argument 'subscription' must be 'ITopicSubscription', not 'Queue'
```
cause You are attempting to pass an SQS `Queue` object directly to `topic.add_subscription()` instead of wrapping it in an `SqsSubscription` construct.

fix Wrap your SQS queue in an `SqsSubscription` construct: `topic.add_subscription(subs.SqsSubscription(queue))`.
```
TypeError: __init__() missing 1 required positional argument: 'scope'
```
cause You are trying to instantiate a construct (like `Topic` or `SqsSubscription`) without providing its `scope` (the parent construct or stack) as the first argument.

fix All constructs require a `scope` and `id`. For example, within a stack method, use `self` as the scope: `sns.Topic(self, "MyTopic", ...)`.

Warnings

breaking AWS CDK v1 is in maintenance mode; AWS CDK v2 is the current major version. V1 packages like `aws-cdk-aws-sns-subscriptions` are replaced by a single `aws-cdk-lib` package in v2, which includes all constructs.
Fix: Migrate your CDK applications to v2 by installing `aws-cdk-lib` and `constructs`, and updating imports. Refer to the official CDK migration guide for detailed steps: `https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html`
gotcha In CDK v1, each service construct library (e.g., `aws-cdk.aws-sns`, `aws-cdk.aws-sqs`, `aws-cdk.aws-sns-subscriptions`) must be installed as a separate PyPI package. Forgetting to install all required dependencies is a common source of `ModuleNotFoundError`.
Fix: Ensure all necessary CDK v1 modules are installed: `pip install aws-cdk.core aws-cdk.aws-sns aws-cdk.aws-sqs aws-cdk.aws-sns-subscriptions`. For v2, simply install `pip install aws-cdk-lib constructs`.
gotcha When subscribing a resource (like an SQS queue or Lambda function) to an SNS topic, ensure the topic has the necessary permissions to send messages to that resource. While `SqsSubscription` often handles basic permissions, complex scenarios or custom policies might require explicit `addToResourcePolicy` calls on the receiving resource.
Fix: Review the generated CloudFormation template for the subscription's IAM permissions. If messages are not being delivered, check the resource policy of the subscriber (e.g., `sqs.QueuePolicy` for SQS queues) to explicitly allow `sns:Publish` actions from the topic's ARN.

Install

pip install aws-cdk.core aws-cdk.aws-sns aws-cdk.aws-sqs aws-cdk.aws-sns-subscriptions Install for CDK v1
pip install aws-cdk-lib constructs Install for CDK v2 (recommended)

Imports

SqsSubscription
wrong:
```
from aws_cdk_lib.aws_sns_subscriptions import SqsSubscription
```
correct:
```
from aws_cdk.aws_sns_subscriptions import SqsSubscription
```
For CDK v1, modules are imported from `aws_cdk.<service>`. For CDK v2, they are consolidated under `aws_cdk.aws_<service>` after installing `aws-cdk-lib`.
LambdaSubscription
```
from aws_cdk.aws_sns_subscriptions import LambdaSubscription
```
The import path remains consistent between v1 and v2, but the underlying package changes from `aws-cdk-aws-sns-subscriptions` (v1) to `aws-cdk-lib` (v2).

Quickstart

This quickstart demonstrates how to create an AWS SNS topic and subscribe an SQS queue to it using the `aws-cdk-aws-sns-subscriptions` module. It defines a simple CDK stack, instantiates an SQS queue and an SNS topic, and then uses `subs.SqsSubscription` to link them. The `app.synth()` call generates the CloudFormation template.

import os
import aws_cdk as cdk
import aws_cdk.aws_sns as sns
import aws_cdk.aws_sqs as sqs
import aws_cdk.aws_sns_subscriptions as subs

# A basic CDK App and Stack
class MySnsSubscriptionStack(cdk.Stack):
    def __init__(self, scope: cdk.App, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # Create an SQS queue to be subscribed
        queue = sqs.Queue(self, "MySubscriptionQueue",
            queue_name="MyTestSubscriptionQueue",
            visibility_timeout=cdk.Duration.seconds(300)
        )

        # Create an SNS topic
        topic = sns.Topic(self, "MySubscriptionTopic",
            display_name="My Test Topic for Subscriptions"
        )

        # Subscribe the SQS queue to the SNS topic using SqsSubscription
        topic.add_subscription(
            subs.SqsSubscription(queue)
        )

        # Output the queue URL and topic ARN for verification
        cdk.CfnOutput(self, "QueueUrl", value=queue.queue_url)
        cdk.CfnOutput(self, "TopicArn", value=topic.topic_arn)

# Instantiate the CDK app and deployable stack
app = cdk.App()
MySnsSubscriptionStack(app, "MySnsSubscriptionStack")
app.synth() # Generates AWS CloudFormation template

view raw JSON →