Sensu RocketChat Handler

• Overview
• Usage examples
  • Help output
  • Environment variables
  • Templates
  • Annotations
• Configuration
  • Asset registration
  • Handler definition
  • Check definition
• Installation from source and contributing

Overview

The Sensu RocketChat Handler is a Sensu Event Handler that sends event data
to a configured RocketChat channel.

Usage examples

Help output

Help:

Usage:
  sensu-rocketchat-handler [flags]
  sensu-rocketchat-handler [command]

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

Flags:
  -c, --channel string                RocketChat channel to send messages to. (Required)
  -u, --url string                    RocketChat service URL (default "http://localhost:3000")
  -t, --description-template string   The RocketChat notification output template, in Golang text/template format (default "{{ .Check.Output }}")
      --alias string                  Name to use in the RocketChat msg. (Note: user must have bot role to take effect) (default "sensu")
      --avatar-url string             Avatar image url to use in RocketChat msg. (Note: user must have bot role to take effect) (default "https://www.sensu.io/img/sensu-logo.png")
  -P, --password string               RocketChat User Password. Used with --user. Note for security using ROCKETCHAT_PASSWORD environment variable is preferred
  -U, --user string                   RocketChat User. Used with --password. Note for security using ROCKETCHAT_USER environment variable is preferred
  -T, --token string                  RocketChat Auth Token. Used with --userID Note for security using ROCKETCHAT_TOKEN environment variable is preferred
  -I, --userID string                 RocketChat Auth UserID. Used with --token. Note for security using ROCKETCHAT_USERID environment variable is preferred
  -v, --verbose                       Verbose output
  -n, --dry-run                       Used for testing, do not communicate with RocketChat API, report only (implies --verbose)
  -h, --help                          help for sensu-rocketchat-handler

Note: The avatar-url and alias configuration options can only be used if the authenticated user is a member of the bot Rocketchat role. The handler will attempt to determine if the authenticated RocketChat user has permissions to set these features, and if it does not will disable alias and avatar-url overrides.

Environment variables

Security Note: Care should be taken to not expose the user/password or token/userID authentication
credentials for this handler by specifying them on the command line or by directly setting the environment
variable in the handler definition. It is suggested to make use of secrets management to surface these as
an environment variables. The handler definition referenced here uses secrets for the authentication credentials.
Below is an example secrets definition that make use of the built-in env secrets provider.

---
type: Secret
api_version: secrets/v1
metadata:
  name: rocketchat_user
spec:
  provider: env
  id: ROCKETCHAT_USER
---
type: Secret
api_version: secrets/v1
metadata:
  name: rocketchat_password
spec:
  provider: env
  id: ROCKETCHAT_PASSWORD
---
type: Secret
api_version: secrets/v1
metadata:
  name: rocketchat_token
spec:
  provider: env
  id: ROCKETCHAT_TOKEN
---
type: Secret
api_version: secrets/v1
metadata:
  name: rocketchat_userid
spec:
  provider: env
  id: ROCKETCHAT_USERID

Templates

This handler provides options for using templates to populate the SumoLogic HTTP source attributes.
By default the source host is populated using a template to extract the Sensu entity name. The default
source name is populated using a template to extract the Sensu check name. More information on template
syntax and format can be found in the documentation

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/rocketchat/config.

NOTE: Due to check token substituion, supplying a template value such
as for description-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 customize the channel for a given entity, you could use the following
sensu-agent configuration snippet:

# /etc/sensu/agent.yml example
annotations:
  sensu.io/plugins/rocketchat/config/channel: '#monitoring'

Configuration

Asset registration

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

sensuctl asset add sensu/sensu-rocketchat-handler

If you're using an earlier version of sensuctl, you can download the asset
definition from this project's Bonsai Asset Index
page.

Handler definition

Create the handler using the following handler definition:

---
api_version: core/v2
type: Handler
metadata:
  namespace: default
  name: rocketchat
spec:
  type: pipe
  command: sensu-rocketchat-handler --channel '#general' --url 'http://rocketchat.yourdomain.com'
  filters:
  - is_incident
  runtime_assets:
  - sensu/sensu-rocketchat-handler
  secrets:
  - name: ROCKETCHAT_PASSWORD
    secret: rocketchat_password
  - name: ROCKETCHAT_USER
    secret: rocketchat_user
  timeout: 10

Security Note: The Rocketchat authentication credentials user/password or token/userID
should always be treated as a security sensitive configuration options and in this example,
they are loaded into the handler configuration as an environment variable using a secret.
Command arguments are commonly readable from the process table by other unprivaledged
users on a system (ex: ps and top commands), so it's a better practise to read
in sensitive information via environment variables or configuration files on
disk. The cmdline argument flags for credentials are provided as overrides for testing purposes.

Check definition

api_version: core/v2
type: CheckConfig
metadata:
  namespace: default
  name: dummy-app-healthz
spec:
  command: check-http -u http://localhost:8080/healthz
  subscriptions:
  - dummy
  publish: true
  interval: 10
  handlers:
  - rocketchat

Proxy Support

This handler supports the use of the environment variables HTTP_PROXY,
HTTPS_PROXY, and NO_PROXY (or the lowercase versions thereof). HTTPS_PROXY takes
precedence over HTTP_PROXY for https requests. The environment values may be
either a complete URL or a "host[:port]", in which case the "http" scheme is assumed.

Installing from source and contributing

Download the latest version of the sensu-rocketchat-handler from releases,
or create an executable from this source.

Compiling

From the local path of the sensu-rocketchat-handler repository:

go build

To contribute to this plugin, see CONTRIBUTING