feat!: Add support for SNS topic filtering, subscriptions, and topic policy creation

.pre-commit-config.yaml

@@ -3,6 +3,7 @@ repos:
     rev: v1.77.0
     hooks:
       - id: terraform_fmt
+      - id: terraform_wrapper_module_for_each
       - id: terraform_validate
       - id: terraform_docs
         args:

README.md

@@ -2,34 +2,146 @@
 
 Terraform module which creates SNS resources on AWS
 
+[![SWUbanner](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg)](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md)
+
 ## Usage
 
+### Simple Topic
+
+```hcl
+module "sns_topic" {
+  source  = "terraform-aws-modules/sns/aws"
+
+  name  = "simple"
+
+  tags = {
+    Environment = "dev"
+    Terraform   = "true"
+  }
+}
+```
+
+### Topic w/ SQS Subscription
+
+```hcl
+module "sns_topic" {
+  source  = "terraform-aws-modules/sns/aws"
+
+  name  = "pub-sub"
+
+  topic_policy_statements = {
+    pub = {
+      actions = ["sns:Publish"]
+      principals = [{
+        type        = "AWS"
+        identifiers = ["arn:aws:iam::66666666666:role/publisher"]
+      }]
+    },
+
+    sub = {
+      actions = [
+        "sns:Subscribe",
+        "sns:Receive",
+      ]
+
+      principals = [{
+        type        = "AWS"
+        identifiers = ["*"]
+      }]
+
+      conditions = [{
+        test     = "StringLike"
+        variable = "sns:Endpoint"
+        values   = ["arn:aws:sqs:eu-west-1:11111111111:subscriber"]
+      }]
+    }
+  }
+
+  subscriptions = {
+    sqs = {
+      protocol = "sqs"
+      endpoint = "arn:aws:sqs:eu-west-1:11111111111:subscriber"
+    }
+  }
+
+  tags = {
+    Environment = "dev"
+    Terraform   = "true"
+  }
+}
+```
+
+### FIFO Topic w/ FIFO SQS Subscription
+
 ```hcl
 module "sns_topic" {
   source  = "terraform-aws-modules/sns/aws"
-  version = "~> 3.0"
 
   name  = "my-topic"
+
+  # SQS queue must be FIFO as well
+  fifo_topic                  = true
+  content_based_deduplication = true
+
+  topic_policy_statements = {
+    pub = {
+      actions = ["sns:Publish"]
+      principals = [{
+        type        = "AWS"
+        identifiers = ["arn:aws:iam::66666666666:role/publisher"]
+      }]
+    },
+
+    sub = {
+      actions = [
+        "sns:Subscribe",
+        "sns:Receive",
+      ]
+
+      principals = [{
+        type        = "AWS"
+        identifiers = ["*"]
+      }]
+
+      conditions = [{
+        test     = "StringLike"
+        variable = "sns:Endpoint"
+        values   = ["arn:aws:sqs:eu-west-1:11111111111:subscriber.fifo"]
+      }]
+    }
+  }
+
+  subscriptions = {
+    sqs = {
+      protocol = "sqs"
+      endpoint = "arn:aws:sqs:eu-west-1:11111111111:subscriber.fifo"
+    }
+  }
+
+  tags = {
+    Environment = "dev"
+    Terraform   = "true"
+  }
 }
 ```
 
 ## Examples
 
-- [Complete SNS topics](https://github.com/terraform-aws-modules/terraform-aws-sns/tree/master/examples/complete)
+- [Complete](https://github.com/terraform-aws-modules/terraform-aws-sns/tree/master/examples/complete)
 
 <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 ## Requirements
 
 | Name | Version |
 |------|---------|
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.0 |
-| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 4.0 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 4.40 |
 
 ## Providers
 
 | Name | Version |
 |------|---------|
-| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 4.0 |
+| <a name="provider_aws"></a> [aws](#provider\_aws) | >= 4.40 |
 
 ## Modules
 
@@ -40,45 +152,47 @@ No modules.
 | Name | Type |
 |------|------|
 | [aws_sns_topic.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/sns_topic) | resource |
+| [aws_sns_topic_policy.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/sns_topic_policy) | resource |
+| [aws_sns_topic_subscription.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/sns_topic_subscription) | resource |
+| [aws_caller_identity.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source |
+| [aws_iam_policy_document.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
 
 ## Inputs
 
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
-| <a name="input_application_failure_feedback_role_arn"></a> [application\_failure\_feedback\_role\_arn](#input\_application\_failure\_feedback\_role\_arn) | IAM role for failure feedback | `string` | `null` | no |
-| <a name="input_application_success_feedback_role_arn"></a> [application\_success\_feedback\_role\_arn](#input\_application\_success\_feedback\_role\_arn) | The IAM role permitted to receive success feedback for this topic | `string` | `null` | no |
-| <a name="input_application_success_feedback_sample_rate"></a> [application\_success\_feedback\_sample\_rate](#input\_application\_success\_feedback\_sample\_rate) | Percentage of success to sample | `string` | `null` | no |
+| <a name="input_application_feedback"></a> [application\_feedback](#input\_application\_feedback) | Map of IAM role ARNs and sample rate for success and failure feedback | `map(string)` | `{}` | no |
 | <a name="input_content_based_deduplication"></a> [content\_based\_deduplication](#input\_content\_based\_deduplication) | Boolean indicating whether or not to enable content-based deduplication for FIFO topics. | `bool` | `false` | no |
-| <a name="input_create_sns_topic"></a> [create\_sns\_topic](#input\_create\_sns\_topic) | Whether to create the SNS topic | `bool` | `true` | no |
+| <a name="input_create"></a> [create](#input\_create) | Determines whether resources will be created (affects all resources) | `bool` | `true` | no |
+| <a name="input_create_subscription"></a> [create\_subscription](#input\_create\_subscription) | Determines whether an SNS subscription is created | `bool` | `true` | no |
+| <a name="input_create_topic_policy"></a> [create\_topic\_policy](#input\_create\_topic\_policy) | Determines whether an SNS topic policy is created | `bool` | `true` | no |
 | <a name="input_delivery_policy"></a> [delivery\_policy](#input\_delivery\_policy) | The SNS delivery policy | `string` | `null` | no |
 | <a name="input_display_name"></a> [display\_name](#input\_display\_name) | The display name for the SNS topic | `string` | `null` | no |
+| <a name="input_enable_default_topic_policy"></a> [enable\_default\_topic\_policy](#input\_enable\_default\_topic\_policy) | Specifies whether to enable the default topic policy. Defaults to `true` | `bool` | `true` | no |
 | <a name="input_fifo_topic"></a> [fifo\_topic](#input\_fifo\_topic) | Boolean indicating whether or not to create a FIFO (first-in-first-out) topic | `bool` | `false` | no |
-| <a name="input_firehose_failure_feedback_role_arn"></a> [firehose\_failure\_feedback\_role\_arn](#input\_firehose\_failure\_feedback\_role\_arn) | IAM role for failure feedback | `string` | `null` | no |
-| <a name="input_firehose_success_feedback_role_arn"></a> [firehose\_success\_feedback\_role\_arn](#input\_firehose\_success\_feedback\_role\_arn) | The IAM role permitted to receive success feedback for this topic | `string` | `null` | no |
-| <a name="input_firehose_success_feedback_sample_rate"></a> [firehose\_success\_feedback\_sample\_rate](#input\_firehose\_success\_feedback\_sample\_rate) | Percentage of success to sample | `number` | `null` | no |
-| <a name="input_http_failure_feedback_role_arn"></a> [http\_failure\_feedback\_role\_arn](#input\_http\_failure\_feedback\_role\_arn) | IAM role for failure feedback | `string` | `null` | no |
-| <a name="input_http_success_feedback_role_arn"></a> [http\_success\_feedback\_role\_arn](#input\_http\_success\_feedback\_role\_arn) | The IAM role permitted to receive success feedback for this topic | `string` | `null` | no |
-| <a name="input_http_success_feedback_sample_rate"></a> [http\_success\_feedback\_sample\_rate](#input\_http\_success\_feedback\_sample\_rate) | Percentage of success to sample | `string` | `null` | no |
+| <a name="input_firehose_feedback"></a> [firehose\_feedback](#input\_firehose\_feedback) | Map of IAM role ARNs and sample rate for success and failure feedback | `map(string)` | `{}` | no |
+| <a name="input_http_feedback"></a> [http\_feedback](#input\_http\_feedback) | Map of IAM role ARNs and sample rate for success and failure feedback | `map(string)` | `{}` | no |
 | <a name="input_kms_master_key_id"></a> [kms\_master\_key\_id](#input\_kms\_master\_key\_id) | The ID of an AWS-managed customer master key (CMK) for Amazon SNS or a custom CMK | `string` | `null` | no |
-| <a name="input_lambda_failure_feedback_role_arn"></a> [lambda\_failure\_feedback\_role\_arn](#input\_lambda\_failure\_feedback\_role\_arn) | IAM role for failure feedback | `string` | `null` | no |
-| <a name="input_lambda_success_feedback_role_arn"></a> [lambda\_success\_feedback\_role\_arn](#input\_lambda\_success\_feedback\_role\_arn) | The IAM role permitted to receive success feedback for this topic | `string` | `null` | no |
-| <a name="input_lambda_success_feedback_sample_rate"></a> [lambda\_success\_feedback\_sample\_rate](#input\_lambda\_success\_feedback\_sample\_rate) | Percentage of success to sample | `string` | `null` | no |
+| <a name="input_lambda_feedback"></a> [lambda\_feedback](#input\_lambda\_feedback) | Map of IAM role ARNs and sample rate for success and failure feedback | `map(string)` | `{}` | no |
 | <a name="input_name"></a> [name](#input\_name) | The name of the SNS topic to create | `string` | `null` | no |
-| <a name="input_name_prefix"></a> [name\_prefix](#input\_name\_prefix) | The prefix name of the SNS topic to create | `string` | `null` | no |
-| <a name="input_policy"></a> [policy](#input\_policy) | The fully-formed AWS policy as JSON | `string` | `null` | no |
-| <a name="input_sqs_failure_feedback_role_arn"></a> [sqs\_failure\_feedback\_role\_arn](#input\_sqs\_failure\_feedback\_role\_arn) | IAM role for failure feedback | `string` | `null` | no |
-| <a name="input_sqs_success_feedback_role_arn"></a> [sqs\_success\_feedback\_role\_arn](#input\_sqs\_success\_feedback\_role\_arn) | The IAM role permitted to receive success feedback for this topic | `string` | `null` | no |
-| <a name="input_sqs_success_feedback_sample_rate"></a> [sqs\_success\_feedback\_sample\_rate](#input\_sqs\_success\_feedback\_sample\_rate) | Percentage of success to sample | `string` | `null` | no |
-| <a name="input_tags"></a> [tags](#input\_tags) | A mapping of tags to assign to all resources | `map(string)` | `{}` | no |
+| <a name="input_override_topic_policy_documents"></a> [override\_topic\_policy\_documents](#input\_override\_topic\_policy\_documents) | List of IAM policy documents that are merged together into the exported document. In merging, statements with non-blank `sid`s will override statements with the same `sid` | `list(string)` | `[]` | no |
+| <a name="input_source_topic_policy_documents"></a> [source\_topic\_policy\_documents](#input\_source\_topic\_policy\_documents) | List of IAM policy documents that are merged together into the exported document. Statements must have unique `sid`s | `list(string)` | `[]` | no |
+| <a name="input_sqs_feedback"></a> [sqs\_feedback](#input\_sqs\_feedback) | Map of IAM role ARNs and sample rate for success and failure feedback | `map(string)` | `{}` | no |
+| <a name="input_subscriptions"></a> [subscriptions](#input\_subscriptions) | A map of subscription definitions to create | `any` | `{}` | no |
+| <a name="input_tags"></a> [tags](#input\_tags) | A map of tags to add to all resources | `map(string)` | `{}` | no |
+| <a name="input_topic_policy"></a> [topic\_policy](#input\_topic\_policy) | An externally created fully-formed AWS policy as JSON | `string` | `null` | no |
+| <a name="input_topic_policy_statements"></a> [topic\_policy\_statements](#input\_topic\_policy\_statements) | A map of IAM policy [statements](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document#statement) for custom permission usage | `any` | `{}` | no |
+| <a name="input_use_name_prefix"></a> [use\_name\_prefix](#input\_use\_name\_prefix) | Determines whether `name` is used as a prefix | `bool` | `false` | no |
 
 ## Outputs
 
 | Name | Description |
 |------|-------------|
-| <a name="output_sns_topic_arn"></a> [sns\_topic\_arn](#output\_sns\_topic\_arn) | ARN of SNS topic |
-| <a name="output_sns_topic_id"></a> [sns\_topic\_id](#output\_sns\_topic\_id) | ID of SNS topic |
-| <a name="output_sns_topic_name"></a> [sns\_topic\_name](#output\_sns\_topic\_name) | NAME of SNS topic |
-| <a name="output_sns_topic_owner"></a> [sns\_topic\_owner](#output\_sns\_topic\_owner) | OWNER of SNS topic |
+| <a name="output_subscriptions"></a> [subscriptions](#output\_subscriptions) | Map of subscriptions created and their attributes |
+| <a name="output_topic_arn"></a> [topic\_arn](#output\_topic\_arn) | The ARN of the SNS topic, as a more obvious property (clone of id) |
+| <a name="output_topic_id"></a> [topic\_id](#output\_topic\_id) | The ARN of the SNS topic |
+| <a name="output_topic_name"></a> [topic\_name](#output\_topic\_name) | The name of the topic |
+| <a name="output_topic_owner"></a> [topic\_owner](#output\_topic\_owner) | The AWS Account ID of the SNS topic owner |
 <!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
 
 ## Authors

UPGRADE-5.0.md

@@ -0,0 +1,142 @@
+# Upgrade from v4.x to v5.x
+
+If you have any questions regarding this upgrade process, please consult the [`examples`](https://github.com/terraform-aws-modules/terraform-aws-sns/tree/master/examples/complete) directory:
+
+If you find a bug, please open an issue with supporting configuration to reproduce.
+
+## List of backwards incompatible changes
+
+- `create_sns_topic` has been renamed to `create`
+- `policy` has been renamed to `topic_policy`
+- `name_prefix` has been replaced with the combination of `name` and `use_name_prefix = true` to ensure only one value is provided
+- `*_failure_feedback_role_arn`, `*_success_feedback_role_arn`, `*_success_feedback_sample_rate` variables have been replaced with a respective top level variable that contains a map to the three attributes. See before and after below for further clarification.
+- Outputs have had the `sns_` prefix stripped from their names
+
+## Additional changes
+
+### Added
+
+- Support for topic policy creation and subscriptions
+
+### Variable and output changes
+
+1. Removed variables:
+
+    - None
+
+2. Renamed variables:
+
+    - `create_sns_topic` -> `create`
+    - `policy` -> `topic_policy`
+    - `application_feedback_failure_role_arn`/`application_feedback_success_role_arn`/`application_feedback_success_feedback_sample_rate` -> `application_feedback`
+    - `firehose_feedback_failure_role_arn`/`firehose_feedback_success_role_arn`/`firehose_feedback_success_feedback_sample_rate` -> `firehose_feedback`
+    - `http_feedback_failure_role_arn`/`http_feedback_success_role_arn`/`http_feedback_success_feedback_sample_rate` -> `http_feedback`
+    - `lambda_feedback_failure_role_arn`/`lambda_feedback_success_role_arn`/`lambda_feedback_success_feedback_sample_rate` -> `lambda_feedback`
+    - `sqs_feedback_failure_role_arn`/`sqs_feedback_success_role_arn`/`sqs_feedback_success_feedback_sample_rate` -> `sqs_feedback`
+
+3. Added variables:
+
+    - `use_name_prefix`
+    - `create_topic_policy`
+    - `source_topic_policy_documents`
+    - `override_topic_policy_documents`
+    - `enable_default_topic_policy`
+    - `topic_policy_statements`
+    - `create_subscription`
+    - `subscriptions`
+
+4. Removed outputs:
+
+    - None
+
+5. Renamed outputs:
+
+    - `sns_` prefix removed from all outputs
+
+6. Added outputs:
+
+    - `subscriptions`
+
+## Upgrade Migrations
+
+Note: Only the affected attributes are shown below for brevity.
+
+### Before 4.x Example
+
+```hcl
+module "sns" {
+  source  = "terraform-aws-modules/sns/aws"
+  version = "~> 4.0"
+
+  create_sns_topic = true
+
+  name_prefix = "example-"
+  policy      = "..."
+
+  application_feedback_failure_role_arn    = "arn:aws:sqs:eu-west-1:11111111111:application"
+  application_feedback_success_role_arn    = "arn:aws:sqs:eu-west-1:11111111111:application"
+  application_feedback_success_sample_rate = 100
+
+  firehose_feedback_failure_role_arn    = "arn:aws:sqs:eu-west-1:11111111111:firehose"
+  firehose_feedback_success_role_arn    = "arn:aws:sqs:eu-west-1:11111111111:firehose"
+  firehose_feedback_success_sample_rate = 100
+
+  http_feedback_failure_role_arn    = "arn:aws:sqs:eu-west-1:11111111111:http"
+  http_feedback_success_role_arn    = "arn:aws:sqs:eu-west-1:11111111111:http"
+  http_feedback_success_sample_rate = 100
+
+  lambda_feedback = {
+  lambda_feedback_failure_role_arn    = "arn:aws:sqs:eu-west-1:11111111111:lambda"
+  lambda_feedback_success_role_arn    = "arn:aws:sqs:eu-west-1:11111111111:lambda"
+  lambda_feedback_success_sample_rate = 100
+
+  sqs_feedback_failure_role_arn    = "arn:aws:sqs:eu-west-1:11111111111:sqs"
+  sqs_feedback_success_role_arn    = "arn:aws:sqs:eu-west-1:11111111111:sqs"
+  sqs_feedback_success_sample_rate = 100
+}
+```
+
+### After 5.x Example
+
+```hcl
+module "sns" {
+  source  = "terraform-aws-modules/sns/aws"
+  version = "~> 5.0"
+
+  create = true
+
+  name            = "example-"
+  use_name_prefix = true
+  topic_policy    = "..."
+
+  application_feedback = {
+    failure_role_arn    = "arn:aws:sqs:eu-west-1:11111111111:application"
+    success_role_arn    = "arn:aws:sqs:eu-west-1:11111111111:application"
+    success_sample_rate = 100
+  }
+  firehose_feedback = {
+    failure_role_arn    = "arn:aws:sqs:eu-west-1:11111111111:firehose"
+    success_role_arn    = "arn:aws:sqs:eu-west-1:11111111111:firehose"
+    success_sample_rate = 100
+  }
+  http_feedback = {
+    failure_role_arn    = "arn:aws:sqs:eu-west-1:11111111111:http"
+    success_role_arn    = "arn:aws:sqs:eu-west-1:11111111111:http"
+    success_sample_rate = 100
+  }
+  lambda_feedback = {
+    failure_role_arn    = "arn:aws:sqs:eu-west-1:11111111111:lambda"
+    success_role_arn    = "arn:aws:sqs:eu-west-1:11111111111:lambda"
+    success_sample_rate = 100
+  }
+  sqs_feedback = {
+    failure_role_arn    = "arn:aws:sqs:eu-west-1:11111111111:sqs"
+    success_role_arn    = "arn:aws:sqs:eu-west-1:11111111111:sqs"
+    success_sample_rate = 100
+  }
+}
+```
+
+### State Changes
+
+No state changes required.

examples/README.md

@@ -0,0 +1,8 @@
+# Examples
+
+Please note - the examples provided serve two primary means:
+
+1. Show users working examples of the various ways in which the module can be configured and features supported
+2. A means of testing/validating module changes
+
+Please do not mistake the examples provided as "best practices". It is up to users to consult the AWS service documentation for best practices, usage recommendations, etc.