search

builtinnya / aws-sns-slack-terraform

A Terraform module which sends SNS events to Slack with AWS lambda function
Apache License 2.0
79 stars 32 forks source link
aws aws-lambda aws-sns terraform terraform-modules

readme

aws-sns-slack-terraform

Minimal CloudWatch Screenshot

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:

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"
  # Or use the following source if your Terraform version >= 0.12
  # source = "github.com/builtinnya/aws-sns-slack-terraform/module-v0.12"

  slack_webhook_url = "https://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}"
}

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(string) n/a yes
slack_webhook_url Slack incoming webhook URL (with or without protocol name) string n/a 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 AR

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.

NOTE: for terraform >= 0.12, see examples/minimal-v0.12 instead.

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="https://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="https://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.