AWS SNS Terraform Module

terraform-aws-arc-sns

Overview

The ARC Terraform module provides an easy and consistent way to create and manage Amazon SNS topics on AWS. This module supports defining topics, subscriptions, and policies, making it simple to connect services like S3, Lambda, and SQS. By using this module, you can quickly set up reliable messaging and notification workflows while following AWS best practices.

Prerequisites

Before using this module, ensure you have the following:

• AWS credentials configured.
• Terraform installed.
• A working knowledge of Terraform.

Getting Started

1. Define the Module

Initially, it's essential to define a Terraform module, which is organized as a distinct directory encompassing Terraform configuration files. Within this module directory, input variables and output values must be defined in the variables.tf and outputs.tf files, respectively. The following illustrates an example directory structure:

sns/
|-- main.tf
|-- variables.tf
|-- outputs.tf

2. Define Input Variables

Inside the variables.tf or in *.tfvars file, you should define values for the variables that the module requires.

3. Use the Module in Your Main Configuration In your main Terraform configuration file (e.g., main.tf), you can use the module. Specify the source of the module, and version, For Example

module "sns" {
  source               = "sourcefuse/arc-sns/aws"
  version              = "0.0.1"

  name                 = var.topic_name
  display_name         = var.display_name

  tags = module.tags.tags
}

4. Output Values

Inside the outputs.tf file of the module, you can define output values that can be referenced in the main configuration. For example:

output "topic_arn" {
  description = "ARN of the created SNS topic"
  value       = module.basic_sns_topic.topic_arn
}

output "topic_name" {
  description = "Name of the created SNS topic"
  value       = module.basic_sns_topic.topic_name
}

5. .tfvars

Inside the .tfvars file of the module, you can provide desired values that can be referenced in the main configuration.

First Time Usage

uncomment the backend block in main.tf

terraform init -backend-config=config.dev.hcl

If testing locally, terraform init should be fine

Create a dev workspace

terraform workspace new dev

Plan Terraform

terraform plan -var-file dev.tfvars

Apply Terraform

terraform apply -var-file dev.tfvars

Production Setup

terraform init -backend-config=config.prod.hcl

Create a prod workspace

terraform workspace new prod

Plan Terraform

terraform plan -var-file prod.tfvars

Apply Terraform

terraform apply -var-file prod.tfvars  

Requirements

Name	Version
terraform	>= 1.5.0
aws	~> 5.0

Providers

Name	Version
aws	4.67.0

Modules

No modules.

Resources

Name	Type
aws_lambda_permission.external_lambda	resource
aws_lambda_permission.sns_invoke	resource
aws_sns_topic.this	resource
aws_sns_topic_subscription.this	resource

Inputs

Name	Description	Type	Default	Required
application_feedback	Map of IAM role ARNs and sample rate for success and failure feedback	object({ failure_role_arn = optional(string) success_role_arn = optional(string) success_sample_rate = optional(number) })	{}	no
archive_policy	The message archive policy for FIFO topics	string	null	no
content_based_deduplication	Enables content-based deduplication for FIFO topics	bool	false	no
create_subscription	Whether to create SNS subscriptions	bool	true	no
create_topic	Whether to create the SNS topic	bool	true	no
delivery_policy	The SNS delivery policy	string	null	no
display_name	Display name for the SNS topic	string	null	no
fifo_throughput_scope	Enables higher throughput for FIFO topics by adjusting the scope of deduplication. Valid values: Topic, MessageGroup	string	null	no
fifo_topic	Boolean indicating whether or not to create a FIFO (first-in-first-out) topic	bool	false	no
firehose_feedback	Map of IAM role ARNs and sample rate for success and failure feedback	object({ failure_role_arn = optional(string) success_role_arn = optional(string) success_sample_rate = optional(number) })	{}	no
http_feedback	Map of IAM role ARNs and sample rate for success and failure feedback	object({ failure_role_arn = optional(string) success_role_arn = optional(string) success_sample_rate = optional(number) })	{}	no
kms_master_key_id	The ID of an AWS-managed customer master key (CMK) for Amazon SNS or a custom CMK	string	null	no
lambda_feedback	Map of IAM role ARNs and sample rate for success and failure feedback	object({ failure_role_arn = optional(string) success_role_arn = optional(string) success_sample_rate = optional(number) })	{}	no
lambda_permissions	Map of Lambda function ARNs that should be granted permission to be invoked by this SNS topic	map(string)	{}	no
name	Name of the SNS topic	string	n/a	yes
policy	The fully-formed AWS policy as JSON	string	null	no
signature_version	The signature version corresponds to the hashing algorithm used while creating the signature of the notifications	number	null	no
sqs_feedback	Map of IAM role ARNs and sample rate for success and failure feedback	object({ failure_role_arn = optional(string) success_role_arn = optional(string) success_sample_rate = optional(number) })	{}	no
subscriptions	A map of subscription configurations	map(object({ protocol = string endpoint = string confirmation_timeout_in_minutes = optional(number, 1) endpoint_auto_confirms = optional(bool, false) raw_message_delivery = optional(bool, false) filter_policy = optional(string) filter_policy_scope = optional(string) delivery_policy = optional(string) redrive_policy = optional(string) }))	{}	no
tags	A map of tags to assign to the resource	map(string)	{}	no
tracing_config	Tracing mode of an Amazon SNS topic	string	null	no
use_name_prefix	Determines whether name is used as a prefix	bool	false	no

Outputs

Name	Description
subscriptions	Map of subscriptions created and their attributes
topic_arn	The ARN of the SNS topic
topic_display_name	The display name of the SNS topic
topic_id	The ID of the SNS topic
topic_name	The name of the SNS topic
topic_owner	The AWS Account ID of the SNS topic owner

Versioning

This project uses a .version file at the root of the repo which the pipeline reads from and does a git tag.

When you intend to commit to main, you will need to increment this version. Once the project is merged, the pipeline will kick off and tag the latest git commit.

Development

Prerequisites

• terraform
• terraform-docs
• pre-commit
• golang
• golint

Configurations

• Configure pre-commit hooks

  pre-commit install

Versioning

while Contributing or doing git commit please specify the breaking change in your commit message whether its major,minor or patch

For Example

git commit -m "your commit message #major"

By specifying this , it will bump the version and if you don't specify this in your commit message then by default it will consider patch and will bump that accordingly

Tests

• Tests are available in test directory
• Configure the dependencies

  cd test/
  go mod init github.com/sourcefuse/terraform-aws-refarch-<module_name>
  go get github.com/gruntwork-io/terratest/modules/terraform

• Now execute the test

  go test -timeout  30m

Authors

This project is authored by:

• SourceFuse ARC Team