Select Supported Platforms

Select Supported Architectures

Select Tier

Github Name


v1.0.0 · public · Published about 4 years ago

Asset Definition
Release Notes
Release Assets

Sensu Bonsai Asset
Go Test

Sensu Maintenance Mode Handler

Table of Contents


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

  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

  -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 "")
  -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.


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

type: Handler
api_version: core/v2
  name: sensu-maintenance-mode-handler
  namespace: default
  command: sensu-maintenance-mode-handler
  type: pipe
  - sensu/sensu-maintenance-mode-handler
  - 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
  name: registration
  namespace: default
  - 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.

Argument 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
  name: sensu_api_key
  provider: env

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.


All arguments for this handler are tunable on a per entity or check basis based on annotations. The
annotations keyspace for this handler is


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

annotations: "2h"


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'

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

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

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.


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

Are you sure you want to report this asset?

Please describe the reason for reporting this asset. Our moderators will be notified and will disable the asset if it is found to be inappropriate.


You must be signed in to report this asset.

Sign In with Github



This asset is enterprise only and requires an enterprise license. By clicking download, you agree to the Sensu terms and conditions and license agreement.