sensu-aws-sns-handler

README

Sensu AWS SNS Handler

Table of Contents

• Overview
• Usage examples
  • Help output
  • Templates
• Configuration
  • Asset registration
  • Handler definition
  • Annotations
  • AWS Credentials
  • Region support
• Installation from source
• Additional notes
• Contributing

Overview

The sensu-aws-sns-handler is a Sensu Handler that allows you to send alerts via AWS Simple Notification Service (SNS).

Usage examples

Help output

AWS Simple Notification Service Handler

Usage:
  sensu-aws-sns-handler [flags]
  sensu-aws-sns-handler [command]

Available Commands:
  help        Help about any command
  version     Print the version number of this plugin

Flags:
  -t, --topic-arn string          The SNS Topic ARN
  -s, --subject-template string   The template for the subject sent via SNS (default "{{.Check.State}} - {{.Entity.Name}}/{{.Check.Name}}")
  -m, --message-template string   The template for the message sent via SNS (default "{{.Entity.Name}}/{{.Check.Name}}: {{.Check.State}}")
  -a, --assume-role-arn string    The IAM role to assume upon succssful authentication
  -u, --use-ec2-region            Query the EC2 metadata for the region to use for SNS
  -h, --help                      help for sensu-aws-sns-handler

Templates

This handler provides options for using templates to populate the values provided by the event in the message sent via SNS. More information on template syntax and format can be found in the documentation

Configuration

Asset registration

Sensu Assets are the best way to make use of this plugin. If you're not using an asset, please consider doing so! If you're using sensuctl 5.13 with Sensu Backend 5.13 or later, you can use the following command to add the asset:

sensuctl asset add sensu/sensu-aws-sns-handler

If you're using an earlier version of sensuctl, you can find the asset on the Bonsai Asset Index.

Handler definition

---
type: Handler
api_version: core/v2
metadata:
  name: sensu-aws-sns-handler
  namespace: default
spec:
  command: sensu-aws-sns-handler
  type: pipe
  runtime_assets:
  - nixiwz/sensu-aws-sns-handler

Annotations

All arguments for this handler are tunable on a per entity or check basis based on annotations. The annotations keyspace for this handler is sensu.io/plugins/sensu-aws-sns-handler/config.

NOTE: Due to check token substituion, supplying a template value such as for message-template as a check annotation requires that you place the desired template as a golang string literal (enlcosed in backticks) within another template definition. This does not apply to entity annotations.

Examples

To change the SNS topic ARN for a particular entity, in that agent's agent.yml file add the following:

annotations:
  sensu.io/plugins/sensu-aws-sns-handler/config/topic-arn: "arn:aws:sns:us-west-2:0123456789012:sensu-alerts"

To change the message template for a particular check, for that checks's metadata add the following:

type: CheckConfig
api_version: core/v2
metadata:
  annotations:
    fatigue_check/occurrences: "3"
    sensu.io/plugins/sensu-aws-sns-handler/config/message-template: "{{`{{.Entity.Name}}/{{.Check.Name}}: {{.Check.State}}, {{.Check.Occurrences}}`}}"
[...]

AWS Credentials

This plugin makes use of the AWS SDK for Go. The SDK uses the default credential provider chain to find AWS credentials. The SDK uses the first provider in the chain that returns credentials without an error. The default provider chain looks for credentials in the following order:

1. Environment variables (AWS_SECRET_ACCESS_KEY, AWS_ACCESS_KEY_ID, and AWS_REGION).

2. Shared credentials file (typically ~/.aws/credentials).

3. If your application is running on an Amazon EC2 instance, IAM role for Amazon EC2.

4. If your application uses an ECS task definition or RunTask API operation, IAM role for tasks.

The SDK detects and uses the built-in providers automatically, without requiring manual configurations. For example, if you use IAM roles for Amazon EC2 instances, your applications automatically use the instance’s credentials. You don’t need to manually configure credentials in your application.

Source: Configuring the AWS SDK for Go

This plugin also supports assuming a new role upon authentication using the --assume-role-arn option.

If you go the route of using environment variables, it is highly suggested you use them via the Env secrets provider.

Region support

The AWS SDK for Go uses the following criteria for determining the AWS region in which to use SNS:

1. The AWS_REGION environment variable
2. The shared configuration file (typically ~/.aws/config)

If running the Sensu backend process on an EC2 instance, this handler also supports using the EC2 metadata to determine the region via the --use-ec2-region option.

Installation from source

The preferred way of installing and deploying this plugin is to use it as an Asset. If you would like to compile and install the plugin from source or contribute to it, download the latest version or create an executable from this source.

From the local path of the sensu-aws-sns-handler repository:

go build

Contributing

For more information about contributing to this plugin, see Contributing.