Terraform AWS Notifications

Description

The purpose of this module is to provide a building block for processing and delivering notifications, sourced from SNS and forwarded to one or more endpoints (email, slack, teams and or custom subscribers).

Usage

module "notifications" {
  source = "github.com/appvia/terraform-aws-notifications?ref=main"

  allowed_aws_services = ["cloudwatch.amazonaws.com"]
  create_sns_topic     = true
  sns_topic_name       = var.sns_topic_name
  tags                 = var.tags

  subscribers = {
    "opsgenie" = {
      protocol               = "https"
      endpoint               = "https://api.opsgenie.com/v2/alerts"
      endpoint_auto_confirms = true
      raw_message_delivery   = true
    }
  }

  email = {
    addresses = var.email_addresses
  }

  enable_slack = true
  teams = {
    webhook_url = var.teams_webhook
  }
  enable_teams = true
  slack = {
    webhook_url = var.slack_webhook
  }

  accounts_id_to_name = {
    "12345678"  = "mgmt",
    "123456789" = "audit"
  }

  post_icons_url = {
    error_url   = "https://raw.githubusercontent.com/appvia/terraform-aws-notifications/main/resources/posts-attention-icon.png"
    warning_url = "https://raw.githubusercontent.com/appvia/terraform-aws-notifications/main/resources/posts-warning-icon.png"
  }

  # To redirect event URL in post through Identity Center, e.g.:
  identity_center_start_url = "<your start url>"
  identity_center_role      = "<your role - consistent across all accounts - namely read only>
}

Update Documentation

The terraform-docs utility is used to generate this README. Follow the below steps to update:

1. Make changes to the .terraform-docs.yml file
2. Fetch the terraform-docs binary (https://terraform-docs.io/user-guide/installation/)
3. Run terraform-docs markdown table --output-file ${PWD}/README.md --output-mode inject .

Using Secrets Manager

The slack configuration can be sourced from AWS Secrets Manager, using the var.slack.secret_name. The secret should be a JSON object reassembling the slack configuration.

{
  "webhook_url": "https://hooks.slack.com/services/..."
}

Maintenance

Frequently (quartley at least) check and upgrade:

1. Python runtime - python_runtime
2. AWS PowerTools Lambda Layer for python ARN: powertools_layer_arn_suffix

Acknowledgements

• notify-teams - distributed under Apache 2.0 license; obligations met under this GNU V3 license
• terraform-aws-notify-slack - distributed under Apache 2.0 license; obligations met under this GNU V3 license

Providers

Name	Version
aws	>= 5.0.0

Inputs

Name	Description	Type	Default	Required
sns_topic_name	The name of the source sns topic where events are published	string	n/a	yes
tags	Tags to apply to all resources	map(string)	n/a	yes
accounts_id_to_name	A mapping of account id and account name - used by notification lamdba to map an account ID to a human readable name	map(string)	{}	no
allowed_aws_principals	Optional, list of AWS accounts able to publish via the SNS topic (when creating topic) e.g 123456789012	list(string)	[]	no
allowed_aws_services	Optional, list of AWS services able to publish via the SNS topic (when creating topic) e.g cloudwatch.amazonaws.com	list(string)	[]	no
cloudwatch_log_group_kms_key_id	The KMS key id to use for encrypting the cloudwatch log group (default is none)	string	null	no
cloudwatch_log_group_retention	The retention period for the cloudwatch log group (for lambda function logs) in days	string	"0"	no
create_sns_topic	Whether to create an SNS topic for notifications	bool	false	no
email	The configuration for Email notifications	object({ addresses = optional(list(string)) # The email addresses to send notifications to })	null	no
enable_slack	To send to slack, set to true	bool	false	no
enable_teams	To send to teams, set to true	bool	false	no
identity_center_role	The name of the role to use when redirecting through Identity Center	string	null	no
identity_center_start_url	The start URL of your Identity Center instance	string	null	no
post_icons_url	URLs (not base64 encoded!) to publically available icons for highlighting posts of error and/or warning status. Ideally 50px square. Set to non-existent URLs to disable icons	object({ error_url = string warning_url = string })	{ "error_url": "https://raw.githubusercontent.com/appvia/terraform-aws-notifications/main/resources/posts-attention-icon.png", "warning_url": "https://raw.githubusercontent.com/appvia/terraform-aws-notifications/main/resources/posts-warning-icon.png" }	no
slack	The configuration for Slack notifications	object({ lambda_name = optional(string, "slack-notify") # The name of the lambda function to create lambda_description = optional(string, "Lambda function to send slack notifications") # The description for the slack lambda secret_name = optional(string) # An optional secret name in secrets manager to use for the slack configuration webhook_url = optional(string) # The webhook url to post to filter_policy = optional(string) # An optional SNS subscription filter policy to apply filter_policy_scope = optional(string) # If filter policy provided this is the scope of that policy; either "MessageAttributes" (default) or "MessageBody" })	null	no
sns_topic_policy	The policy to attach to the sns topic, else we default to account root	string	null	no
subscribers	Optional list of custom subscribers to the SNS topic	map(object({ protocol = string # The protocol to use. The possible values for this are: sqs, sms, lambda, application. (http or https are partially supported, see below). endpoint = string # The endpoint to send data to, the contents will vary with the protocol. (see below for more information) endpoint_auto_confirms = bool # Boolean indicating whether the end point is capable of auto confirming subscription e.g., PagerDuty (default is false) raw_message_delivery = bool # Boolean indicating whether or not to enable raw message delivery (the original message is directly passed, not wrapped in JSON with the original message in the message property) (default is false) }))	{}	no
teams	The configuration for teams notifications	object({ lambda_name = optional(string, "teams-notify") # The name of the lambda function to create lambda_description = optional(string, "Lambda function to send teams notifications") # The description for the teams lambda secret_name = optional(string) # An optional secret name in secrets manager to use for the slack configuration webhook_url = optional(string) # The webhook url to post to filter_policy = optional(string) # An optional SNS subscription filter policy to apply filter_policy_scope = optional(string) # If filter policy provided this is the scope of that policy; either "MessageAttributes" (default) or "MessageBody" })	null	no

Outputs

Name	Description
channels_config	The configuration data for each distribution channel
distributions	The list of slack/teams distributions that are managed
sns_topic_arn	The ARN of the SNS topic