Sensu RocketChat Handler

Overview
Usage examples
Configuration
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

Argument	Environment Variable
--channel	ROCKETCHAT_CHANNEL
--url	ROCKETCHAT_URL
--username	ROCKETCHAT_USER
--password	ROCKETCHAT_PASSWORD
--token	ROCKETCHAT_TOKEN
--userID	ROCKETCHAT_USERID
--alias	ROCKETCHAT_ALIAS
--avatar-url	ROCKETCHAT_AVATAR_URL
--description-template	ROCKETCHAT_DESCRIPTION_TEMPLATE

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 RocketChat msg description. By default the description is populated using a template to extract the Sensu check output. 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

isabella232 / sensu-rocketchat-handler Goto Github PK