Select Supported Platforms

Select Supported Architectures

Select Tier

Github Name


sensu/sensu-maintenance-mode-handler

v1.0.0 · public · Published about 1 month ago

README
Asset Definition
Release Notes
Release Assets

Sensu Bonsai Asset
Go Test
goreleaser

Sensu Maintenance Mode Handler

Table of Contents

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.

Argument Environment Variable
--apiURL SENSU_API_URL
--apiKey SENSU_API_KEY
--apiUser SENSU_API_USER
--apiPassword SENSU_API_PASSWORD
--expires MAINTENANCE_EXPIRES
--reason MAINTENANCE_REASON

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.

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

Download

×

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