Update README

Signed-off-by: Simon Plourde <simon@sensu.io>
sensu · Feb 11, 2020 · fe25e78 · fe25e78
1 parent 98d7ff8
commit fe25e78
Show file tree

Hide file tree

Showing 2 changed files with 80 additions and 95 deletions.
diff --git a/README.md b/README.md
@@ -1,53 +1,60 @@
 [![Bonsai Asset Badge](https://img.shields.io/badge/Sensu%20Slack%20Handler-Download%20Me-brightgreen.svg?colorB=89C967&logo=sensu)](https://bonsai.sensu.io/assets/sensu/sensu-slack-handler) [![Build Status](https://travis-ci.org/sensu/sensu-slack-handler.svg?branch=master)](https://travis-ci.org/sensu/sensu-slack-handler)
 
-# Sensu Go Slack Handler
+# Sensu Slack Handler
 
-The Sensu Slack handler is a [Sensu Event Handler][1] that sends event data to
-a configured Slack channel.
+- [Overview](#overview)
+- [Usage examples](#usage-examples)
+- [Configuration](#configuration)
+  - [Asset registration](#asset-registration)
+  - [Handler definition](#handler-definition)
+  - [Check definition](#check-definition)
+- [Installation from source and
+  contributing](#installation-from-source-and-contributing)
+
+## Overview
+
+
+The [Sensu Slack Handler][0] is a [Sensu Event Handler][3] that sends event data
+to a configured Slack channel.
+
+## Usage examples
+
+Help:
+
+```
+Usage:
+  sensu-slack-handler [flags]
+  sensu-slack-handler [command]
+
+Available Commands:
+  help        Help about any command
+  version     Print the version number of this plugin
+
+Flags:
+  -c, --channel string       The channel to post messages to (default "#general")
+  -h, --help                 help for sensu-slack-handler
+  -i, --icon-url string      A URL to an image to use as the user avatar (default "https://www.sensu.io/img/sensu-logo.png")
+  -u, --username string      The username that messages will be sent as (default "sensu")
+  -w, --webhook-url string   The webhook url to send messages to
+```
 
 ## Configuration
 
 ### Asset registration
 
-Assets are the best way to make use of this handler. If you're not using an asset, please consider doing so! If you're using sensuctl 5.13 or later, you can use the following command to add the asset: 
+Assets are the best way to make use of this handler. If you're not using an asset, please consider doing so! If you're using sensuctl 5.13 or later, you can use the following command to add the asset:
 
 `sensuctl asset add sensu/sensu-slack-handler`
 
-If you're using an earlier version of sensuctl, you can download the asset definition from [this project's Bonsai Asset Index page](https://bonsai.sensu.io/assets/sensu/sensu-slack-handler).
-
-#### Example Sensu Go handler definition:
-
-**slack-handler.json**
-
-```json
-{
-    "api_version": "core/v2",
-    "type": "Handler",
-    "metadata": {
-        "namespace": "default",
-        "name": "slack"
-    },
-    "spec": {
-        "type": "pipe",
-        "command": "sensu-slack-handler --channel '#general' --timeout 20 --username 'sensu' ",
-        "env_vars": [
-            "SLACK_WEBHOOK_URL=https://www.webhook-url-for-slack.com"
-        ],
-
-        "timeout": 30,
-        "filters": [
-            "is_incident"
-        ],
-        "runtime_assets": ["sensu-slack-handler"]
-    }
-}
-```
+If you're using an earlier version of sensuctl, you can download the asset
+definition from [this project's Bonsai Asset Index
+page][6].
 
-`sensuctl create -f slack-handler.json`
+### Handler definition
 
-**sensu-slack-handler.yml**
+Create the handler using the following handler definition:
 
-```yaml
+```yml
 ---
 api_version: core/v2
 type: Handler
@@ -56,48 +63,28 @@ metadata:
   name: slack
 spec:
   type: pipe
-  command: 'sensu-slack-handler --channel ''#general'' --timeout 20 --username ''sensu'' '
-  env_vars:
-  - SLACK_WEBHOOK_URL=https://www.webhook-url-for-slack.com
-  timeout: 30
+  command: sensu-slack-handler --channel '#general' --username 'sensu'
   filters:
   - is_incident
   runtime_assets:
-  - sensu-slack-handler
+  - sensu/sensu-slack-handler
+  secrets:
+  - name: SLACK_WEBHOOK_URL
+    secret: slack-webhook-url
+  timeout: 10
 ```
 
-`sensuctl create -f slack-handler.yml`
-
-Example Sensu Go check definition:
-
-**check-dummy-app-healthz.json**
-
-```json
-{
-    "api_version": "core/v2",
-    "type": "CheckConfig",
-    "metadata": {
-        "namespace": "default",
-        "name": "dummy-app-healthz"
-    },
-    "spec": {
-        "command": "check-http -u http://localhost:8080/healthz",
-        "subscriptions":[
-            "dummy"
-        ],
-        "publish": true,
-        "interval": 10,
-        "handlers": [
-            "slack"
-        ]
-    }
-}
-```
+**Security Note**: The Slack webhook URL should always be treated as a security
+sensitive configuration option and in this example, it is loaded into the
+handler configuration as an environment variable using a [secret][5]. Command
+arguments are commonly readable from the process table by other unprivaledged
+users on a system (ex: ps and top commands), so it's a better practise to read
+in sensitive information via environment variables or configuration files on
+disk. The --webhook-url flag is provided as an override for testing purposes.
 
-**check-dummy-app-healthz.yml**
+### Check definition
 
-```yaml
----
+```
 api_version: core/v2
 type: CheckConfig
 metadata:
@@ -113,37 +100,35 @@ spec:
   - slack
 ```
 
-**Security Note:** The Slack webhook url is treated as a security sensitive configuration option in this example and is loaded into the handler config as an env_var instead of as a command argument. Command arguments are commonly readable from the process table by other unprivaledged users on a system (ex: `ps` and `top` commands), so it's a better practise to read in sensitive information via environment variables or configuration files on disk. The `--webhook-url` flag is provided as an override for testing purposes.
+### Customizing configuration options via checks and entities
 
-## Usage examples
-
-Help:
+All configuration options of this handler can be overridden via the annotations
+of checks and entities. For example, to customize the channel for a given
+entity, you could use the following sensu-agent configuration snippet:
 
-```
-The Sensu Go Slack handler for notifying a channel
-
-Usage:
-  sensu-slack-handler [flags]
-
-Flags:
-  -c, --channel string       The channel to post messages to (default "#general")
-  -h, --help                 help for handler-slack
-  -i, --icon-url string      A URL to an image to use as the user avatar (default "http://s3-us-west-2.amazonaws.com/sensuapp.org/sensu.png")
-  -t, --timeout int          The amount of seconds to wait before terminating the handler (default 10)
-  -u, --username string      The username that messages will be sent as (default "sensu")
-  -w, --webhook-url string   The webhook url to send messages to, defaults to value of SLACK_WEBHOOK_URL env variable
+```yml
+# /etc/sensu/agent.yml example
+annotations:
+  sensu.io/plugins/slack/config/channel: '#monitoring'
 ```
 
 ## Installing from source and contributing
 
-The preferred way of installing and deploying this plugin is to use it as an [asset]. If you would like to compile and install the plugin from source, or contribute to it, download the latest version of the sensu-slack-handler from [releases][2],
+Download the latest version of the sensu-slack-handler from [releases][4],
 or create an executable script from this source.
 
-From the local path of the slack-handler repository:
+### Compiling
+
+From the local path of the sensu-slack-handler repository:
 ```
-go build -o /usr/local/bin/sensu-slack-handler main.go
+go build
 ```
 
-[1]: https://docs.sensu.io/sensu-go/5.0/reference/handlers/#how-do-sensu-handlers-work
-[2]: https://github.com/sensu/sensu-slack-handler/releases
-[3]: #asset-registration
+To contribute to this plugin, see [CONTRIBUTING](https://github.com/sensu/sensu-go/blob/master/CONTRIBUTING.md)
+
+[0]: https://github.com/sensu/sensu-slack-handler
+[1]: https://github.com/sensu/sensu-go
+[3]: https://docs.sensu.io/sensu-go/latest/reference/handlers/#how-do-sensu-handlers-work
+[4]: https://github.com/sensu/sensu-slack-handler/releases
+[5]: https://docs.sensu.io/sensu-go/latest/reference/secrets/
+[6]: https://bonsai.sensu.io/assets/sensu/sensu-slack-handler
diff --git a/main.go b/main.go
@@ -45,7 +45,7 @@ var (
 			Env:       "SLACK_WEBHOOK_URL",
 			Argument:  webHookURL,
 			Shorthand: "w",
-			Usage:     "The webhook url to send messages to, defaults to value of SLACK_WEBHOOK_URL env variable",
+			Usage:     "The webhook url to send messages to",
 			Value:     &config.slackwebHookURL,
 		},
 		{