From 5ce93a2dcaef92743da65a2d17e796897dfec5e2 Mon Sep 17 00:00:00 2001 From: Jef Spaleta Date: Thu, 24 Sep 2020 11:05:50 -0800 Subject: [PATCH] add quick start section and reorg usage --- README.md | 163 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 97 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index bb1f7c2..de0c7da 100644 --- a/README.md +++ b/README.md @@ -8,16 +8,17 @@ ## Table of Contents - [Overview](#overview) -- [Usage examples](#usage-examples) +- [Quick start](#quick-start) +- [Usage](#usage) - [Help](#help) - [Deduplication Key](#deduplication-key) - [PagerDuty Severity Mapping](#pagerduty-severity-mapping) -- [Configuration](#configuration) - - [Asset registration](#asset-registration) - - [Handler definition](#handler-definition) - [Environment Variables](#environment-variables) - [Argument Annotations](#argument-annotations) - [Proxy support](#proxy-support) +- [Configuration](#configuration) + - [Asset registration](#asset-registration) + - [Handler definition](#handler-definition) - [Installation from source](#installation-from-source) - [Contributing](#contributing) @@ -27,7 +28,17 @@ The Sensu PagerDuty Handler is a [Sensu Event Handler][3] which manages [PagerDuty][2] incidents, for alerting operators. With this handler, [Sensu][1] can trigger and resolve PagerDuty incidents. -## Usage Examples +## Quick Start +The quickest way to get started using this handler plugin, is to install via the monitoring-pipelines [PagerDuty template](https://github.com/sensu-community/monitoring-pipelines/blob/master/incident-management/pagerduty.yaml) +The template provides helpful comments concerning supported options, and includes Sensu resource definitions for the handler and the versioned asset you will need. +You'll want to edit the template to match your configuration before installing with `sensuctl create`. + +Please note that the monitoring-pipeline abd monitoring-checks templates make use of specially defined handler sets by default. +For me information on how the templates work, take a look at the [monitoring pipelines readme](https://github.com/sensu-community/monitoring-pipelines/blob/master/README.md) + + + +## Usage ### Help ``` @@ -52,6 +63,65 @@ Use "sensu-pagerduty-handler [command] --help" for more information about a comm ``` +#### Environment Variables + +Most 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 | +|--------------------|----------------------------| +|--token |PAGERDUTY_TOKEN | +|--summary-template |PAGERDUTY_SUMMARY_TEMPLATE | +|--dedup-key-template|PAGERDUTY_DEDUP_KEY_TEMPLATE| +|--status-map |PAGERDUTY_STATUS_MAP | + +**Security Note:** Care should be taken to not expose the auth token for this +handler by specifying it on the command line or by directly setting the +environment variable in the handler definition. It is suggested to make use of +[secrets management][8] to surface it as an environment variable. The handler +definition above references it as a secret. Below is an example secrets +definition that make use of the built-in [env secrets provider][9]. + +```yml +--- +type: Secret +api_version: secrets/v1 +metadata: + name: pagerduty_token +spec: + provider: env + id: PAGERDUTY_TOKEN +``` + +#### Argument 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-pagerduty-handler/config`. + +###### Examples + +To change the token argument for a particular check, for that checks's metadata +add the following: + +```yml +type: CheckConfig +api_version: core/v2 +metadata: + annotations: + sensu.io/plugins/sensu-pagerduty-handler/config/token: abcde12345fabcd67890efabc12345de +[...] +``` + +#### 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. + ### Deduplication Key The deduplication key is determined via the `--dedup-key-template` argument. It @@ -97,8 +167,9 @@ The valid [PagerDuty alert severity levels][5] are the following: * `error` ## Configuration -### Sensu Go -#### Asset registration +Note: If you are using the monitoring-plugins template, the template provides the asset and handler resource definitions. Please read the inline comments in the template, for more information on template configuration options. + +### Asset registration [Sensu Assets][6] 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 @@ -111,7 +182,25 @@ sensuctl asset add sensu/sensu-pagerduty-handler If you're using an earlier version of sensuctl, you can find the asset on the [Bonsai Asset Index][7]. -#### Handler definition +### Asset definition +Below is an example of a manually created asset definition. You can use this definition with `sensu create` to register a version of this asset without using the bonsai integration. + +```yml +--- +type: Asset +api_version: core/v2 +metadata: + name: sensu-pagerduty-handler_linux_amd64 +spec: + url: https://assets.bonsai.sensu.io/e930fc9c21b835896216ca4594c7990111b54630/sensu-pagerduty-handler_2.0.1_linux_amd64.tar.gz + sha512: 6d499ae6edeb910eb807abfb141be3b9a72951911f804d5a7cc98fbbea15dc4cc6c456f1663124c1db51111c8fd42dab39d1d093356e555785f21ef5f95ffb06 + filters: + - entity.system.os == 'linux' + - entity.system.arch == 'amd64' +``` + + +### Handler definition ```yml --- @@ -133,64 +222,6 @@ spec: secret: pagerduty_authtoken ``` -#### Environment Variables - -Most 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 | -|--------------------|----------------------------| -|--token |PAGERDUTY_TOKEN | -|--summary-template |PAGERDUTY_SUMMARY_TEMPLATE | -|--dedup-key-template|PAGERDUTY_DEDUP_KEY_TEMPLATE| -|--status-map |PAGERDUTY_STATUS_MAP | - -**Security Note:** Care should be taken to not expose the auth token for this -handler by specifying it on the command line or by directly setting the -environment variable in the handler definition. It is suggested to make use of -[secrets management][8] to surface it as an environment variable. The handler -definition above references it as a secret. Below is an example secrets -definition that make use of the built-in [env secrets provider][9]. - -```yml ---- -type: Secret -api_version: secrets/v1 -metadata: - name: pagerduty_token -spec: - provider: env - id: PAGERDUTY_TOKEN -``` - -#### Argument 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-pagerduty-handler/config`. - -###### Examples - -To change the token argument for a particular check, for that checks's metadata -add the following: - -```yml -type: CheckConfig -api_version: core/v2 -metadata: - annotations: - sensu.io/plugins/sensu-pagerduty-handler/config/token: abcde12345fabcd67890efabc12345de -[...] -``` - -#### 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. ## Installation from source