Amazon Simple Notification Service is a cloud-based service that allows you to send notifications to subscribers. You can use SNS to send notifications to mobile devices, email addresses, or other web services. Terraform is a tool that allows you to manage your infrastructure as code. You can use Terraform to create and manage SNS topic subscriptions. In this article, we will show you how to create an SNS topic subscription with Terraform. We will also show you how to test your subscription by sending a notification to the topic.
An SNS topic subscription allows you to receive notifications when messages are published to a topic. When a message is published to a topic, SNS sends a notification to each of the subscribers for that topic. The subscription definition in Terraform captures the criteria for receiving those notifications and binds the delivery mechanism to the topic identified by its ARN.
Understanding SNS Topic Subscriptions in Terraform
An SNS topic subscription in Terraform is a configuration that defines the criteria for receiving notifications from an SNS topic. When a message is published to an SNS topic, all subscriptions that match the criteria will receive a copy of the message.
The resource is aws_sns_topic_subscription. It provides a resource for subscribing to SNS topics. Requires that an SNS topic exist for the subscription to attach to. This resource allows you to automatically place messages sent to SNS topics in SQS queues, send them as HTTP(S) POST requests to a given endpoint, send SMS messages, or notify devices / applications. The most likely use case for Terraform users will probably be SQS queues.
The real world consequence for operators is that a single SNS topic can fan out to many delivery mechanisms without modifying the publisher. The publisher remains unchanged while Terraform codifies the subscription topology.
Resource Creation Prerequisites
To create an SNS topic subscription with Terraform, you need to create a Terraform configuration file that defines the resources you want to create.
To create an SNS topic subscription, you need to provide the topic ARN, the protocol that you want to use to receive notifications, and the endpoint that you want to receive notifications at. You can use Terraform to create SNS topic subscriptions. To do this, you need to define a resource “awssnstopic_subscription” resource for each subscription that you want to create.
To create an SNS topic subscription with Terraform, you need to define the following resources:
- A
aws_sns_topicresource to create the topic. - A
aws_sns_topic_subscriptionresource to create the subscription.
The dependency chain means the topic must be created before the subscription can reference its ARN. This ordering is enforced by Terraform dependency graph.
Core Attributes of awssnstopic_subscription
The topic_arn attribute of the aws_sns_topic_subscription resource must be the ARN of the SNS topic that you want to subscribe to.
Make sure that the protocol is supported. The protocol attribute of the aws_sns_topic_subscription resource must be a supported protocol. For a list of supported protocols, see the AWS documentation.
Make sure that the endpoint is valid. The endpoint attribute of the aws_sns_topic_subscription resource must be a valid endpoint for the specified protocol.
The three types of SNS topic subscriptions referenced in the guidance are:
- Email subscriptions: Email subscriptions send notifications to an email address.
- HTTP/HTTPS subscriptions: HTTP/HTTPS subscriptions send notifications to a URL.
- Lambda subscriptions: Lambda subscriptions invoke a Lambda function when a message is published to the topic.
Example Configuration for Email Subscription
The following example shows how to create an SNS topic subscription with Terraform:
hcl
resource “aws_sns_topic” “my_topic” {
name = “my-topic”
}
resource “aws_sns_topic_subscription” “my_subscription” {
topic_arn = “${aws_sns_topic.my_topic.arn}”
protocol = “email”
endpoint = “[email protected]”
}
A second example creates a subscription for the my-topic topic that sends notifications to the my-email email address:
hcl
resource “aws_sns_topic_subscription” “my-subscription” {
topic_arn = “arn:aws:sns:us-east-1:123456789012:my-topic”
protocol = “email”
endpoint = “[email protected]”
}
The impact of using a hardcoded ARN is that the configuration becomes environment specific. Using an interpolation reference such as ${aws_sns_topic.my_topic.arn} keeps the configuration portable across environments.
Creating Topics and Subscriptions Together
How to create an SNS topic subscription with Terraform.
To create an SNS topic subscription with Terraform, you need to create a Terraform configuration file that defines the resources you want to create.
The configuration file defines the resources you want to create. The resource definition establishes the intent. Terraform translates the intent into AWS API calls.
Updating SNS Topic Subscriptions
To update an SNS topic subscription with Terraform, you can use the update subcommand. For example, the following command updates the endpoint of the SNS topic subscription to [email protected]:
bash
terraform apply -target aws_sns_topic_subscription.my_subscription -var [email protected]
The target flag limits the apply to a single resource. This reduces blast radius during changes.
For more information on managing SNS topic subscriptions with Terraform, see the Terraform documentation.
Deleting SNS Topic Subscriptions
To delete an SNS topic subscription with Terraform, you can use the destroy subcommand.
For example, the following command deletes the SNS topic subscription my_subscription:
bash
terraform destroy -target aws_sns_topic_subscription.my_subscription
To delete an SNS topic subscription in Terraform, you can use the destroy command. The following example deletes the my-subscription subscription:
bash
terraform destroy -target aws_sns_topic_subscription.my-subscription
Destruction removes the subscription from AWS but leaves the topic intact unless the topic resource is also targeted for destruction.
Cross Region and Cross Account Constraints
If the SNS topic and SQS queue are in different AWS regions, the awssnstopicsubscription must use an AWS provider that is in the same region as the SNS topic. If the awssnstopicsubscription uses a provider with a different region than the SNS topic, Terraform will fail to create the subscription.
If an SNS topic and SQS queue are in different AWS accounts but the same region, the awssnstopic_subscription must use the AWS provider for the account with the SQS queue.
Setup of cross-account subscriptions from SNS topics to SQS queues requires Terraform to have access to BOTH accounts.
The operational impact is that provider configuration must mirror the location of the SNS topic, not the queue, and credentials must be present for both accounts to allow Terraform to assume roles and create the subscription. Misalignment produces authentication errors or resource not found errors at apply time.
Troubleshooting Common Problems
There are a few common problems that you may encounter when managing SNS topic subscriptions with Terraform. Here are some tips for troubleshooting these problems:
- Make sure that the AWS region is correct. The
aws_sns_topicandaws_sns_topic_subscriptionresources require theregionattribute to be set to the AWS region where you want to create the resources. - Make sure that the topic ARN is correct. The
topic_arnattribute of theaws_sns_topic_subscriptionresource must be the ARN of the SNS topic that you want to subscribe to. - Make sure that the protocol is supported. The
protocolattribute of theaws_sns_topic_subscriptionresource must be a supported protocol. - Make sure that the endpoint is valid. The
endpointattribute of theaws_sns_topic_subscriptionresource must be a valid endpoint for the specified protocol.
If you are still having problems, you can try the following:
- Check the Terraform logs for errors.
- Contact AWS support for help.
Correct region selection prevents Terraform from creating resources in the wrong partition. An incorrect topic ARN leads to a failure to attach the subscription. An unsupported protocol causes validation failure. An invalid endpoint causes SNS to reject the subscription confirmation.
Managing SNS Topic Subscriptions with Terraform
SNS topic subscriptions allow you to receive notifications when messages are published to a topic. You can use Terraform to create, update, and delete SNS topic subscriptions.
How to manage SNS topic subscriptions with Terraform?
SNS topic subscriptions allow you to receive notifications when messages are published to a topic. You can use Terraform to create, update, and delete SNS topic subscriptions.
The lifecycle is fully codified. Creation establishes the subscription. Updates modify attributes such as endpoint or protocol. Deletion removes the subscription.
Using Modules for Reusability
How do I use SNS topic subscriptions with Terraform modules?
You can use SNS topic subscriptions with Terraform modules by referencing the aws_sns_topic_subscription resource in the module’s configuration.
Use Terraform modules to create and manage your SNS topics and subscriptions. This will help you to keep your configuration DRY and consistent.
Modularizing the subscription allows the same subscription pattern to be reused across multiple topics while keeping arguments centralized.
Testing and Validation
Test your SNS topic subscriptions by sending test messages to the topics. This will help you to ensure that your subscriptions are working correctly.
Validation steps include confirming the SNS topic exists, confirming the subscription resource applies without error, and confirming a test message is delivered to the endpoint.
Best Practices for Configuration Management
- Use Terraform modules to create and manage your SNS topics and subscriptions. This will help you to keep your configuration DRY and consistent.
- Test your SNS topic subscriptions by sending test messages to the topics. This will help you to ensure that your subscriptions are working correctly.
The guidance emphasizes keeping configuration DRY and consistent. Consistent naming, consistent provider blocks, and consistent variable definitions reduce drift.
Q and A Reference
Q: What is an SNS topic subscription in Terraform?
A: An SNS topic subscription in Terraform is a configuration that defines the criteria for receiving notifications from an SNS topic. When a message is published to an SNS topic, all subscriptions that match the criteria will receive a copy of the message.
Q: How do I create an SNS topic subscription in Terraform?
A: To create an SNS topic subscription in Terraform, you can use the aws_sns_topic_subscription resource.
The following example creates a subscription for the my-topic topic that sends notifications to the my-email email address:
hcl
resource “aws_sns_topic_subscription” “my-subscription” {
topic_arn = “arn:aws:sns:us-east-1:123456789012:my-topic”
protocol = “email”
endpoint = “[email protected]”
}
Q: How do I delete an SNS topic subscription in Terraform?
A: To delete an SNS topic subscription in Terraform, you can use the destroy command. The following example deletes the my-subscription subscription:
bash
terraform destroy -target aws_sns_topic_subscription.my-subscription
Q: What are the different types of SNS topic subscriptions?
A: There are three types of SNS topic subscriptions:
- Email subscriptions: Email subscriptions send notifications to an email address.
- HTTP/HTTPS subscriptions: HTTP/HTTPS subscriptions send notifications to a URL.
- Lambda subscriptions: Lambda subscriptions invoke a Lambda function when a message is published to the topic.
Q: How do I use SNS topic subscriptions with Terraform modules?
A: You can use SNS topic subscriptions with Terraform modules by referencing the aws_sns_topic_subscription resource in the module’s configuration.
Q: Where can I learn more about SNS topic subscriptions in Terraform?
Here are some resources where you can learn more about SNS topic subscriptions in Terraform:
- Terraform documentation on SNS topic subscriptions
- AWS documentation on SNS topic subscriptions
- Terraform community forum on SNS topic subscriptions
Conclusion
SNS topic subscriptions are a powerful way to receive notifications when messages are published to a topic. Terraform can be used to create, update, and delete SNS topic subscriptions. By following the steps in this guide, you can easily manage SNS topic subscriptions with Terraform.
In this blog post, we discussed how to create an SNS topic subscription using Terraform. We covered the following topics:
- What is SNS and Terraform?
- How to create an SNS topic
- How to create an SNS topic subscription
- How to validate your Terraform configuration
- How to apply your Terraform configuration
The operational value comes from codifying the subscription topology. Codification enables version control, peer review, and repeatable deployments. Region alignment, correct ARNs, supported protocols, and valid endpoints are the four pillars of a successful subscription. Cross region and cross account scenarios add provider constraints and credential requirements that must be explicitly modeled. Using modules, testing deliveries, and targeting specific resources for updates or destruction completes a mature management practice for SNS topic subscriptions with Terraform.