Merge pull request #4 from machadovilaca/jv/improve_docs

Improve documentation
machadovilaca · Mar 28, 2021 · bf2c304 · bf2c304
2 parents bc8bb6a + cc2663b
commit bf2c304
Show file tree

Hide file tree

Showing 3 changed files with 49 additions and 15 deletions.
diff --git a/README.md b/README.md
@@ -1,17 +1,47 @@
 # terraform-aws-notifications
 
 [![Terraform CI](https://github.com/mvg-org/terraform-aws-notifications/actions/workflows/workflow.yaml/badge.svg)](https://github.com/mvg-org/terraform-aws-notifications/actions/workflows/workflow.yaml)
+![Terraform Version](https://img.shields.io/badge/Terraform-0.12+-green.svg)
+[![Terraform Module Registry](https://img.shields.io/badge/Terraform%20Module%20Registry-latest-blue.svg)](https://registry.terraform.io/modules/machadovilaca/notifications/aws/latest)
+[![License: GPL](https://img.shields.io/badge/License-GPL-green.svg)](https://opensource.org/licenses/GPL-3.0)
 
+## Description
+
+This Terraform module allows you to subscribe to notifications from both SNS
+topics and Cloudwatch log groups. For each of those, you can select where do you
+want to send the notifications to. You have the option to target Slack and/or
+and an S3 bucket.
+
+Subscriptions can be made to any AWS service that sends information to any of the
+previously described sources. In the following example, you can see the
+subscription for SNS alerts concerning 'Bounce', 'Complaint' and 'Delivery' from
+an SES instance, and an alert from Cloudwatch for an SNS mobile message sent.
+
+### Message Formating
+
+**This module supports all messages sent to the subscribed systems**. However,
+as most alerts have a different structure, if one alert message is not currently supported by this module, the notification text will fallback to the alert raw
+content. The supported alerts will be pretty-printed as described in the
+[formats](files/notifications/formats) folder.
+
+Currently being pretty-printed:
+
+- [RDS Notification Messages](files/notifications/formats/rds.py)
+
+- [SES Delivery Status Alerts](files/notifications/formats/ses.py)
+
+- [SMS Deliveries](files/notifications/formats/sms.py)
 
 ## Example Usage
 
 ```
 module "notifications" {
-  source = "github.com/mvg-org/terraform-aws-notifications"
+  source  = "machadovilaca/notifications/aws"
+  version = "0.0.1"
 
   aws_region = var.aws_region
 
-  slack_webhook_url = "https://hooks.slack.com/services/XPTOXPTO/XPTOXPTOXPTOXPTOXPTOXPTOXPTOXPTO"
+  slack_webhook_url = "https://hooks.slack.com/services/MI8EILOH9/EECHAHQUOONGAHK2FU4LAIC7IEZ6EIBA8"
   slack_channel     = "#sns-notifications"
   slack_username    = "sns-notifcations"
 
@@ -37,7 +67,6 @@ module "notifications" {
   }
 }
 ```
-
 ## Requirements
 
 | Name | Version |
@@ -72,13 +101,13 @@ No modules.
 
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
-| <a name="input_aws_region"></a> [aws\_region](#input\_aws\_region) | AWS region | `any` | n/a | yes |
+| <a name="input_aws_region"></a> [aws\_region](#input\_aws\_region) | AWS region | `string` | n/a | yes |
 | <a name="input_cloudwatch_subscripted_log_group_names"></a> [cloudwatch\_subscripted\_log\_group\_names](#input\_cloudwatch\_subscripted\_log\_group\_names) | Cloudwatch log groups subscribed to lambda | `map` | `{}` | no |
 | <a name="input_create_bucket"></a> [create\_bucket](#input\_create\_bucket) | Should create bucket? | `bool` | `true` | no |
-| <a name="input_s3_bucket_name"></a> [s3\_bucket\_name](#input\_s3\_bucket\_name) | S3 bucket name | `any` | n/a | yes |
-| <a name="input_slack_channel"></a> [slack\_channel](#input\_slack\_channel) | Slack channel to send notifications to | `any` | n/a | yes |
-| <a name="input_slack_username"></a> [slack\_username](#input\_slack\_username) | Slack username that will publish notifications | `any` | n/a | yes |
-| <a name="input_slack_webhook_url"></a> [slack\_webhook\_url](#input\_slack\_webhook\_url) | Slack incoming-webhook url | `any` | n/a | yes |
+| <a name="input_s3_bucket_name"></a> [s3\_bucket\_name](#input\_s3\_bucket\_name) | S3 bucket name | `string` | n/a | yes |
+| <a name="input_slack_channel"></a> [slack\_channel](#input\_slack\_channel) | Slack channel to send notifications to | `string` | n/a | yes |
+| <a name="input_slack_username"></a> [slack\_username](#input\_slack\_username) | Slack username that will publish notifications | `string` | n/a | yes |
+| <a name="input_slack_webhook_url"></a> [slack\_webhook\_url](#input\_slack\_webhook\_url) | Slack incoming-webhook url | `string` | n/a | yes |
 | <a name="input_sns_subscripted_topics_arns"></a> [sns\_subscripted\_topics\_arns](#input\_sns\_subscripted\_topics\_arns) | SNS topic arns subscribed to lambda | `map` | `{}` | no |
 
 ## Outputs

diff --git a/files/notifications/examples/ses.json b/files/notifications/examples/ses.json
@@ -3,18 +3,18 @@
         {
             "EventSource": "aws:sns",
             "EventVersion": "1.0",
-            "EventSubscriptionArn": "arn:aws:sns:eu-west-1: 526266413792:ses_tst_deliveries: 52cf7de9-e401-437c-a1cd-6ae0d09802c7",
+            "EventSubscriptionArn": "arn:aws:sns:eu-west-1: 674284732940:ses_tst_deliveries: 7830dbb5-4d95-4b2c-8358-277bcf049c5a",
             "Sns": {
                 "Type": "Notification",
-                "MessageId": "da11fbf3-8cea-5920-ae7a-a3618e0b1cc1",
-                "TopicArn": "arn:aws:sns:eu-west-1:526266413792:ses_tst_deliveries",
+                "MessageId": "7830dbb5-4d95-4b2c-8358-277bcf049c5a",
+                "TopicArn": "arn:aws:sns:eu-west-1:674284732940:ses_tst_deliveries",
                 "Subject": "None",
-                "Message": "{\"notificationType\": \"Delivery\",\"mail\": {\"timestamp\": \"2021-02-01T13:22:40.910Z\",\"source\": \"no-reply@tst.publicmint.io\",\"sourceArn\": \"arn:aws:ses:eu-west-1:526266413792:identity/tst.publicmint.io\",\"sourceIp\": \"99.80.107.240\",\"sendingAccountId\": \"526266413792\",\"messageId\": \"010201775dc2748e-0afc4009-6919-4493-860d-ebc7b0206ed5-000000\",\"destination\": [\"joaovilaca@seegno.com\"],\"headersTruncated\": false,\"headers\": [{\"name\": \"From\",\"value\": \"no-reply@tst.publicmint.io\"},{\"name\": \"To\",\"value\": \"joaovilaca@seegno.com\"},{\"name\": \"Subject\",\"value\": \"Please confirm your account\"},{\"name\": \"MIME-Version\",\"value\": \"1.0\"},{\"name\": \"Content-Type\",\"value\": \"multipart/alternative;  boundary=\\\"----=_Part_2789201_1205165557.1612185760912\\\"\"}],\"commonHeaders\": {\"from\": [\"no-reply@tst.publicmint.io\"],\"to\": [\"joaovilaca@seegno.com\"],\"subject\": \"Please confirm your account\"}},\"delivery\": {\"timestamp\": \"2021-02-01T13:22:41.948Z\",\"processingTimeMillis\": 1038,\"recipients\": [\"joaovilaca@seegno.com\"],\"smtpResponse\": \"250 2.0.0 OK  1612185761 d17si15939505wrj.495 - gsmtp\",\"remoteMtaIp\": \"74.125.193.27\",\"reportingMTA\": \"a7-42.smtp-out.eu-west-1.amazonses.com\"}}",
+                "Message": "{\"notificationType\": \"Delivery\",\"mail\": {\"timestamp\": \"2021-02-01T13:22:40.910Z\",\"source\": \"no-reply@publicmint.com\",\"sourceArn\": \"arn:aws:ses:eu-west-1:674284732940:identity/tst.publicmint.io\",\"sourceIp\": \"100.30.17.130\",\"sendingAccountId\": \"674284732940\",\"messageId\": \"7830dbb5-4d95-4b2c-8358-277bcf049c5a\",\"destination\": [\"joaovilaca@seegno.com\"],\"headersTruncated\": false,\"headers\": [{\"name\": \"From\",\"value\": \"no-reply@publicmint.com\"},{\"name\": \"To\",\"value\": \"joaovilaca@seegno.com\"},{\"name\": \"Subject\",\"value\": \"Please confirm your account\"},{\"name\": \"MIME-Version\",\"value\": \"1.0\"},{\"name\": \"Content-Type\",\"value\": \"multipart/alternative;  boundary=\\\"----=_Part_2789201_1205165557.1612185760912\\\"\"}],\"commonHeaders\": {\"from\": [\"no-reply@publicmint.com\"],\"to\": [\"joaovilaca@seegno.com\"],\"subject\": \"Please confirm your account\"}},\"delivery\": {\"timestamp\": \"2021-02-01T13:22:41.948Z\",\"processingTimeMillis\": 1038,\"recipients\": [\"joaovilaca@seegno.com\"],\"smtpResponse\": \"250 2.0.0 OK  1612185761 Ohch2Jio1Eicaeza7.495 - gsmtp\",\"remoteMtaIp\": \"21.35.123.37\",\"reportingMTA\": \"b3-23.smtp-out.eu-west-1.amazonses.com\"}}",
                 "Timestamp": "2021-02-01T13: 22: 41.990Z",
                 "SignatureVersion": "1",
-                "Signature": "JrZu33thR7UHqWZFPIdXPsm3QxzpBdMs+UaXST1A+x5xff212WHuZBt4o35b+lx2Wpx3+9sbdtJB0Tux8/tm3F3YoMAOO4Al5T+aSEngleLbFCim9MxXDMTYL11FUvkvKTxjXyR06/p9o3T/UeB6qbJ+0WaBbirmLiidM+Wm2TRbb2R1zUzZlYAE7SDGAvhl7NxyPN7YkO2bxK73+2FBP49xL8bB3lSYKvJ1L6n6H8d86QU6c9M0hf0TaQU1MxCGZsJ6gDu842njVLOxEG739P2591QRfW2++3MDTOJ6xPgUuEt0q0ZpJpyNWQTxJ5MUB0NjeYAb6b7lwb8gr0T/hA==",
-                "SigningCertUrl": "https: //sns.eu-west-1.amazonaws.com/SimpleNotificationService-010a507c1833636cd94bdb98bd93083a.pem",
-                "UnsubscribeUrl": "https://sns.eu-west-1.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:eu-west-1:526266413792:ses_tst_deliveries:52cf7de9-e401-437c-a1cd-6ae0d09802c7",
+                "Signature": "ZWl2ZWlnaDZqb0JpNmllam9oNWFobTFvaGphaGdpZXRhZXBoNkFlZjZsYWlrZWVadWVwb2w1QmllNVBhcGg0RWdlZTZxdW96YWg5SXo3ZnUyb2k3QWVrOWFpRmVlN2FodGg3T29XZWk3aWVtNXBob29qYWlHNnppMGllcGFoY2g0eGllc2hhaTRhaWNhaW4yZ2FlY2VlOEhlaW43dGFoNmJ1Ym9lNHppZVdhbmVpOG5haWc0dmVpdG9ocjBnb283b293N25laTRwYTZCdUwxc2FlNEFlNVlvZTNlZXJhZWdpaU1haWYwVGVyZWl2YWljaHVqdW8wb29kb2E4aWU1VA==",
+                "SigningCertUrl": "https: //sns.eu-west-1.amazonaws.com/SimpleNotificationService-eithail0aipeeYukupheef1xoetahch0o.pem",
+                "UnsubscribeUrl": "https://sns.eu-west-1.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:eu-west-1:674284732940:ses_tst_deliveries:7830dbb5-4d95-4b2c-8358-277bcf049c5a",
                 "MessageAttributes": {}
             }
         }

diff --git a/variables.tf b/variables.tf
@@ -1,21 +1,26 @@
 variable "aws_region" {
   description = "AWS region"
+  type        = string
 }
 
 variable "slack_webhook_url" {
   description = "Slack incoming-webhook url"
+  type        = string
 }
 
 variable "slack_channel" {
   description = "Slack channel to send notifications to"
+  type        = string
 }
 
 variable "slack_username" {
   description = "Slack username that will publish notifications"
+  type        = string
 }
 
 variable "s3_bucket_name" {
   description = "S3 bucket name"
+  type        = string
 }
 
 variable "create_bucket" {