Sensu Maintenance Mode Handler

Table of Contents

• Overview
• Enterprise Plugin
• Usage examples
• Configuration
  • Asset registration
  • Handler definition
  • Proxy support
  • Annotations
  • RBAC
• Contributing

Overview

The Sensu Maintenance Mode Handler is a Sensu Handler that silences the entity from a generated
event for a specified time period and reason. The expected use case would be as a
registration handler that automatically places new entites into a maintenance mode while they
are being deployed/provisioned.

Enterprise Plugin

The Sensu Maintenance Mode 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)

Usage examples

Sensu Maintenance Mode Handler

Usage:
  sensu-maintenance-mode-handler [flags]
  sensu-maintenance-mode-handler [command]

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

Flags:
  -k, --apiKey string            Sensu Go Backend API Key
  -P, --apiPassword string       Sensu Go Backend API Password for specified user (default "P@ssw0rd!")
  -U, --apiURL string            Sensu Go Backend URL (default "http://127.0.0.1:8080")
  -u, --apiUser string           Sensu Go Backend API User (default "admin")
  -e, --expires string           When to expire silencing (e.g. 1200s, 15m, 3h), supported periods are s(econds), m(inutes), or h(ours) (default "1h")
  -h, --help                     help for sensu-maintenance-mode-handler
  -i, --insecure-skip-verify     skip TLS certificate verification (not recommended!)
  -r, --reason string            Reason to list for the silencing (default "Provisioning")
  -t, --trusted-ca-file string   TLS CA certificate bundle in PEM format

Use "sensu-maintenance-mode-handler [command] --help" for more information about a command.

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-maintenance-mode-handler

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

Handler definition

To use as a registration handler, the handler (or handler set) needs to be named registration.
Best practice would be to use a handler set and add this handler to it. To do so, first create the
handler.

---
type: Handler
api_version: core/v2
metadata:
  name: sensu-maintenance-mode-handler
  namespace: default
spec:
  command: sensu-maintenance-mode-handler
  type: pipe
  runtime_assets:
  - sensu/sensu-maintenance-mode-handler
  secrets:
  - name: SENSU_API_KEY
    secret: sensu_api_key

Then create the handler set with the above handler defined as a member of the set.

---
type: Handler
api_version: core/v2
metadata:
  name: registration
  namespace: default
spec:
  handlers:
  - sensu-maintenance-mode-handler
  type: set

Environment Variables

Several arguments for this handler are available to be set via environment variables. However, any
arguments specified directly on the command line override the corresponding environment variable.

Security Note: Care should be taken to not expose the username/password and/or the API key for this
handler by specifying them on the command line. It is suggested to make use of secrets management
to surface them as environment variables. The handler definition above references them as secrets. Below
is an example secret definition that makes use of the built-in env secrets provider.

---
type: Secret
api_version: secrets/v1
metadata:
  name: sensu_api_key
spec:
  provider: env
  id: SENSU_API_KEY

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-maintenance-mode-handler/config.

Examples

To change the expires argument for a particular entity, in that entity's agent.yml add the following:

[...]
annotations:
  sensu.io/plugins/sensu-maintenance-mode-handler/config/expires: "2h"
[...]

RBAC

It is advised to use RBAC to create a user scoped specifically for purposes such as this handler and
to not re-use the admin account. For this handler, in particular, the account would need access to
create silenced entries. The example below shows how to create this limited-scope user and the necessary
role and role-binding resources to give it the required access.

sensuctl user create maintenance --password='4yva#ko!Yq'
Created

sensuctl role create silenced-only --verb create --resource silenced
Created

sensuctl role-binding create maintenance-silenced-only --role=silenced-only --user=maintenance
Created

Though you could use the user and password combination above with this handler, the best practice
would be to use an API key instead. You can create the API key with sensuctl:

sensuctl api-key grant maintenance
Created: /api/core/v2/apikeys/03f66dbf-6fe0-40d4-8174-95b5eab95649

The key (the text after [...]/apikeys/) above can be used with the --apiKey argument in place of using apiUser and apiPassword.

Contributing

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