add quick start section and reorg usage

sensu · Sep 24, 2020 · 5ce93a2 · 5ce93a2
1 parent e930fc9
commit 5ce93a2
Showing 1 changed file with 97 additions and 66 deletions.
diff --git 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