aws-sns-slack-terraform

This is a Terraform module which maps an AWS SNS topic name to a Slack channel. The AWS Lambda function code it uses is derived from robbwagoner/aws-lambda-sns-to-slack.

The supported features are:

• Posting AWS SNS notifications to Slack channels
• Building necessary AWS resources by Terraform automatically
• Customizable topic-to-channel map

Usage

aws-sns-slack-terraform is a Terraform module. You just need to include the module in one of your Terraform scripts and set up SNS topics and permissions. See examples/ for concrete examples.

module "sns_to_slack" {
  source = "github.com/builtinnya/aws-sns-slack-terraform/module"

  slack_webhook_url = "hooks.slack.com/services/XXXXXXXXX/XXXXXXXXX/XXXXXXXXXXXXXXXXXXXXXXXX"
  slack_channel_map = {
    "topic-name" = "#slack-channel"
  }

  # The following variables are optional.
  lambda_function_name = "sns-to-slack"
  default_username = "AWS Lambda"
  default_channel = "#webhook-tests"
  default_emoji = ":information_source:"
}

resource "aws_sns_topic" "test_topic" {
  name = "topic-name"
}

resource "aws_lambda_permission" "allow_lambda_sns_to_slack" {
  statement_id = "AllowSNSToSlackExecutionFromSNS"
  action = "lambda:invokeFunction"
  function_name = "${module.sns_to_slack.lambda_function_arn}"
  principal = "sns.amazonaws.com"
  source_arn = "${aws_sns_topic.test_topic.arn}"
}

resource "aws_sns_topic_subscription" "lambda_sns_to_slack" {
  topic_arn = "${aws_sns_topic.test_topic.arn}"
  protocol = "lambda"
  endpoint = "${module.sns_to_slack.lambda_function_arn}"
}

Configurable variables

Inputs

Name	Description	Type	Default	Required
default_channel	Default channel used if no matching channel found	string	#webhook-tests	no
default_emoji	Default emoji used if no matching emoji found	string	:information_source:	no
default_username	Default username for notifications used if no matching one found	string	AWS Lambda	no
lambda_function_name	AWS Lambda function name for the Slack notifier	string	sns-to-slack	no
lambda_iam_policy_name	IAM policy name for lambda functions	string	lambda-sns-to-slack-policy	no
lambda_iam_role_name	IAM role name for lambda functions	string	lambda-sns-to-slack	no
slack_channel_map	Topic-to-channel mapping	map	-	yes
slack_webhook_url	Slack incoming webhook URL without protocol name	string	-	yes
username_prefix	if sepecified the usernames that are looked up will be prefixed by this. Useful in situations where multiple accounts report to a single slack channel.	string	``	no

Outputs

Name	Description
lambda_function_arn	AWS Lambda notifier function ARN

Examples

minimal

The minimal example is located at examples/minimal. It builds no extra AWS resources except a CloudWatch alarm for AWS Lambda's duration metric.

Building steps

1. Move to the examples/minimal directory.

   $ cd examples/minimal

2. Copy secrets.tfvars.example to secrets.tfvars and fill in the values.

   $ cp secrets.tfvars.example secrets.tfvars
   $ # Edit secrets.tfvars using your favorite editor.

   access_key = "<your AWS Access Key>"
   secret_key = "<your AWS Secret Key>"
   region = "<region>"
   slack_webhook_url="hooks.slack.com/services/XXXXXXXXX/XXXXXXXXX/XXXXXXXXXXXXXXXXXXXXXXXX"

3. Execute the following commands to build resources using Terraform.

   $ terraform init
   $ terraform plan -var-file=terraform.tfvars -var-file=secrets.tfvars
   $ terraform apply -var-file=terraform.tfvars -var-file=secrets.tfvars

Destroying resources

To destory AWS resources created by the above steps, execute the following command in examples/minimal directory.

$ terraform destroy -var-file=terraform.tfvars -var-file=secrets.tfvars

Testing

To test notification, use awscli cloudwatch set-alarm-state as following.

$ AWS_ACCESS_KEY_ID=<ACCESS_KEY> \
  AWS_SECRET_ACCESS_KEY=<SECRET> \
  AWS_DEFAULT_REGION=<REGION> \
    aws cloudwatch set-alarm-state \
      --alarm-name lambda-duration \
      --state-value ALARM \
      --state-reason xyzzy

Development

The main AWS Lambda function code is located in sns-to-slack/ directory. To prepare development, you need to use Pipenv for this project and install required dependencies as following.

$ cd sns-to-slack
$ pipenv install

You need to create module/lambda/sns-to-slack.zip to update the code as following.

$ ./build-function.sh

Testing

To test the function locally, just run lambda_function.py with some environment variables.

$ WEBHOOK_URL="hooks.slack.com/services/XXXXXXXXX/XXXXXXXXX/XXXXXXXXXXXXXXXXXXXXXXXX" \
  CHANNEL_MAP=`echo '{ "production-notices": "#webhook-tests" }' | base64` \
  python sns-to-slack/lambda_function.py

Contributors

See CONTRIBUTORS.md.

License

Copyright © 2017-present Naoto Yokoyama

Distributed under the Apache license version 2.0. See the LICENSE file for full details.