Sensu Go Microsoft Teams Handler

Table of Contents

• Overview
• Enterprise Plugin
• Configuration
  • Microsoft Teams channel setup
  • Asset registration
  • Handler definition
  • Proxy support
  • Annotations
• Usage examples
  • Help output
  • Templates
  • Example messages
• Installation from source
• Contributing

Overview

The Sensu Microsoft Teams handler is a Sensu Event Handler that sends
event data to a configured Microsoft Teams channel.

Enterprise Plugin

The Sensu Microsoft Teams Handler is an Enterprise plugin that requires a valid Sensu license to run.
Sensu Go >= 5.21 will add the SENSU_LICENSE_FILE environment variable to the handler execution.
To run the plugin independently of Sensu (ex. test/dev), you must set the env var:

SENSU_LICENSE_FILE=$(sensuctl license info --format json)

Configuration

Microsoft Teams channel setup

This link will help to setup an incoming webhook that is needed by this
plugin.

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-microsoft-teams-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: microsoft-teams
  namespace: default
spec:
  command: sensu-microsoft-teams-handler
  type: pipe
  filters:
    - is_incident
    - not_silenced
  runtime_assets:
    - sensu/sensu-microsoft-teams-handler
  secrets:
    - name: MICROSOFT_TEAMS_WEBHOOK_URL
      secret: microsoft_teams_webhook_url

Security Note: The Microsoft Teams webhook URL is treated as a security
sensitive configuration option in this example and is loaded into the handler
config as a secret instead of as a command argument.

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.

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-microsoft-teams-handler/config.

Examples

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

type: CheckConfig
api_version: core/v2
metadata:
  annotations:
    sensu.io/plugins/sensu-microsoft-teams-handler/config/webhook-url: "https://outlook.office.com/alternate-webhook/"
[...]

Usage examples

Help output

The Sensu Go Microsoft Teams handler for notifying a channel/team

Usage:
  sensu-microsoft-teams-handler [flags]
  sensu-microsoft-teams-handler [command]

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

Flags:
  -i, --icon-url string           The URL for an icon to display in the message (default is no icon)
  -o, --max-output-length int     The maximum event output length to send to Microsoft Teams - 0 for no limit (default 100)
  -m, --message-template string   The template for the message to be sent, in Golang text/template format (default is no template, but a preformatted message)
  -s, --summary-template string   The template for the summary, in Golang text/template format (may not be reflected in Teams client) (default "Sensu Event: {{.Entity.Name}}/{{.Check.Name}}: {{.Check.State}}")
  -t, --title-template string     The template for the title, in Golang text/template format (default "Sensu Event")
  -w, --webhook-url string        The webhook URL to send messages to (default is the value of MICROSOFT_TEAMS_WEBHOOK_URL env variable
  -h, --help                      help for sensu-microsoft-teams-handler

Use "sensu-microsoft-teams-handler [command] --help" for more information about a command.

Templates

This handler provides options for using templates to populate the values
provided by the event in the message, summary, and title fields in a Teams
message. The message template also provides limited support of markdown
to further embellish the message formatting.

More information on template syntax and format can be found in
the documentation

Example messages

All default arguments (critical event)

Notice the format of the message when not using --message-template.

sensu-microsoft-teams-handler

Icon specification (critical event)

sensu-microsoft-teams-handler --icon-url https://www.sensu.io/img/sensu-logo.png

Title template specification (critical event)

sensu-microsoft-teams-handler --title-template "Sensu Event - {{.Entity.Name}}/{{.Check.Name}}"

Message template specification (critical event)

This makes use of the limited markdown support.

sensu-microsoft-teams-handler --message-template "**Entity:** {{.Entity.Name}}\n**Check:** {{.Check.Name}}\n**State:** {{.Check.State}}\n**Output**: {{.Check.Output}}"

All custom arguments (critical event)

sensu-microsoft-teams-handler --message-template "**Entity:** {{.Entity.Name}}\n**Check:** {{.Check.Name}}\n**State:** {{.Check.State}}\n**Output**: {{.Check.Output}}" --title-template "Sensu Event - {{.Entity.Name}}/{{.Check.Name}}" --icon-url https://www.sensu.io/img/sensu-logo.png

All custom arguments (OK event)

sensu-microsoft-teams-handler --message-template "**Entity:** {{.Entity.Name}}\n**Check:** {{.Check.Name}}\n**State:** {{.Check.State}}\n**Output**: {{.Check.Output}}" --title-template "Sensu Event - {{.Entity.Name}}/{{.Check.Name}}" --icon-url https://www.sensu.io/img/sensu-logo.png

Installation from source

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

From the local path of the microsoft-team-handler repository:

go build -o /usr/local/bin/sensu-microsoft-teams-handler main.go

Contributing

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