Merge pull request #153 from flanksource/fix/notifications-docs

feat: notification docs

mission-control/docs/notifications/channels.md

@@ -0,0 +1,26 @@
+# Channels
+
+Mission control uses [Shoutrrr](https://github.com/containrrr/shoutrrr/) under the hood to deliver notifications. Most of the services in the Shoutrrr are supported. Here's the complete list:
+
+| Services    | URL Format                                                                               |
+| ----------- | ---------------------------------------------------------------------------------------- |
+| Bark        | `bark://devicekey@host`                                                                  |
+| Discord     | `discord://token@id `                                                                    |
+| Email       | `smtp://username:password@host:port/?from=fromAddress&to=recipient1[,recipient2,...]`    |
+| Gotify      | `gotify://gotify-host/token`                                                             |
+| Google Chat | `googlechat://chat.googleapis.com/v1/spaces/FOO/messages?key=bar&token=baz `             |
+| IFTTT       | `ifttt://key/?events=event1[,event2,...]&value1=value1&value2=value2&value3=value3   `   |
+| Join        | `join://shoutrrr:api-key@join/?devices=device1[,device2, ...][&icon=icon][&title=title]` |
+| Mattermost  | `mattermost://[username@]mattermost-host/token[/channel]`                                |
+| Matrix      | `matrix://username:password@host:port/[?rooms=!roomID1[,roomAlias2]] `                   |
+| Ntfy        | `ntfy://username:[email protected]/topic`                                                 |
+| OpsGenie    | `opsgenie://host/token?responders=responder1[,responder2]     `                          |
+| Pushbullet  | `pushbullet://api-token[/device/#channel/email]`                                         |
+| Pushover    | `pushover://shoutrrr:apiToken@userKey/?devices=device1[,device2, ...]`                   |
+| Rocketchat  | `rocketchat://[username@]rocketchat-host/token[/channel\| @recipient]`                   |
+| Slack       | `slack://[botname@]token-a/token-b/token-c`                                              |
+| Teams       | `teams://group@tenant/altId/groupOwner?host=organization.webhook.office.com`             |
+| Telegram    | `telegram://token@telegram?chats=@channel-1[,chat-id-1,...]`                             |
+| Zulip Chat  | `zulip://bot-mail:bot-key@zulip-domain/?stream=name-or-id&topic=name`                    |
+
+For more details please visit: [https://containrrr.dev/shoutrrr/0.8/services/overview/](https://containrrr.dev/shoutrrr/0.7/services/overview/)

mission-control/docs/notifications/concepts/filtering.md

@@ -1,21 +1,49 @@
 # Filtering
 
-Customizing notifications is made possible through the use of filters, which are driven by CEL expressions (Check Execution Language). You can learn more about CEL expressions on the [CEL-spec GitHub page](https://github.com/google/cel-spec).
+Customizing notifications is made possible through the use of filters, which are driven by CEL expressions _(Check Execution Language)_.
+
+:::info
+Learn more about CEL expressions [here](../../reference/scripting/cel.md).
+:::
 
 The cel expression receives different input variables based on the event type. To determine which variables are available, refer to the corresponding event details in the [events](../events) section.
 
 ## Examples
 
-```yaml
-# Filter HTTP checks only
-events:
-  - check.passed
-filter: check.type == 'http'
+```yaml title="check-alerts.yaml"
+---
+# Filter HTTP checks that have failed for more than 5 times in the last 1 hour
+apiVersion: mission-control.flanksource.com/v1
+kind: Notification
+metadata:
+  name: check-alerts
+  namespace: default
+spec:
+  events:
+    - check.passed
+    - check.failed
+  filter: check.type == 'http' && check.uptime.failed > 5
+  to:
+    connection: connection://slack/flanksource
+  title: Check {{.check.name}} is {{.check.status}}
 ```
 
-```yaml
-# Filter HTTP checks those that have failed for more than 5 times in the last 1 hour
-events:
-  - check.failed
-filter: check.type == 'http' && check.uptime.failed > 5
+```yaml title="kubernetes-node-component-alerts.yaml"
+---
+# Send all component status alerts for Kubernetes Node component
+apiVersion: mission-control.flanksource.com/v1
+kind: Notification
+metadata:
+  name: kubernetes-node-component-alerts
+  namespace: default
+spec:
+  events:
+    - component.status.healthy
+    - component.status.unhealthy
+    - component.status.warning
+    - component.status.error
+    - component.status.info
+  filter: component.type == "Kubernetes::Node"
+  to:
+    connection: connection://slack/flanksource
 ```

mission-control/docs/notifications/concepts/templating.md

@@ -10,14 +10,45 @@ Templating is essential for crafting customized notifications. It involves using
 
 Go templates are a feature of the Go programming language that allow you to define and execute templates. Templates are text files that contain placeholders for data, which are filled in at runtime. The view data for the template is the [search param](./api.md#search-params).
 
-```yaml
-events:
-  - check.passed
-title: Check as {{.check.status}}
-template: |
-  Canary: {{.canary.name}}
-  {{if .agent}}Agent: {{.agent.name}}{{end}}
-  Message: {{.status.message}}
-filter: "check.type == 'http'"
-. . .
+### Examples
+
+```yaml title="check-alerts.yaml"
+apiVersion: mission-control.flanksource.com/v1
+kind: Notification
+metadata:
+  name: check-alerts
+  namespace: default
+spec:
+  events:
+    - check.passed
+    - check.failed
+  to:
+    connection: connection://slack/flanksource
+  title: Check {{.check.name}} is {{.check.status}}
+  template: |
+    Canary: {{.canary.id}} ({{.canary.name}})
+    Description: {{.check.description}}
+    Type: {{.check.type}}
+```
+
+```yaml title="component-alerts.yaml"
+---
+apiVersion: mission-control.flanksource.com/v1
+kind: Notification
+metadata:
+  name: component-alerts
+  namespace: default
+spec:
+  events:
+    - component.status.healthy
+    - component.status.unhealthy
+    - component.status.warning
+    - component.status.error
+    - component.status.info
+  to:
+    connection: connection://slack/flanksource
+  title: Component {{.component.name}} status changed to {{.component.status}}
+  template: |
+    Description: {{.component.description}}
+    Type: {{.component.type}}
 ```

mission-control/docs/notifications/examples/slack.md

@@ -0,0 +1,89 @@
+# Slack Notification
+
+In this example, we will walk through the process of creating a health check alert notification on slack starting from creating the Slack bot token.
+
+## Create a Slack bot
+
+### Create a new app
+
+Visit https://api.slack.com/apps and create a new app. Use the "From an app manifest" option.
+
+![App Creation](../../images/slack-app-creation.png)
+
+### Set up OAuth permission
+
+After creating the app, you should be navigated to the app's homepage. On the left panel menu, go to Features->OAuth & Permissions. Scroll down and you should see the **"Scopes"** section
+
+![](../../images/slack-app-oauth-scope.png)
+
+Set `chat:write` permission
+
+### Install the Slack app
+
+While still on the same page, scroll up to the "OAuth Tokens for Your Workspace" section. Install the newly created app on your Slack workspace.
+
+![](../../images/slack-app-install-to-workspace.png)
+
+Once you install the app you should see the OAuth token
+
+![](../../images/slack-bot-user-oauth-token.png)
+
+## Set up the notification
+
+### Create kubernetes secret
+
+We'll create a new kubernetes secret using the OAuth token we just created.
+
+```yaml title="slack-secret.yaml"
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: slack
+  namespace: default
+stringData:
+  token: xoxb-910094966996-6596865117477-n7iujSYWmHtnTLMmITdm8z06
+```
+
+### Create Connection
+
+Then, we create a new slack connection using that kubernetes secret. The channel that should receive the notification should go into `spec.username` field.
+
+```yaml title="slack-connection.yaml"
+---
+apiVersion: mission-control.flanksource.com/v1
+kind: Connection
+metadata:
+  name: flanksource
+  namespace: default
+spec:
+  type: slack
+  url:
+    value: slack://$(password)@$(username)
+  username:
+    value: mission-control-notifications # <-- slack channel name
+  password:
+    valueFrom:
+      secretKeyRef:
+        name: slack
+        key: token
+```
+
+### Create notification
+
+```yaml title="http-check-notification.yaml"
+---
+apiVersion: mission-control.flanksource.com/v1
+kind: Notification
+metadata:
+  name: http-check-alerts
+  namespace: default
+spec:
+  events:
+    - check.passed
+    - check.failed
+  to:
+    # use the slack connection as the recipient for this notification
+    connection: connection://slack/flanksource
+  filter: check.type == 'http'
+```

mission-control/docs/notifications/overview.md

@@ -2,75 +2,43 @@
 
 Notification allows you to receive alerts on a preferred channel when a particular set of events occur.
 
-| Category                                                                 | event                        | Description                                                                                |
-| ------------------------------------------------------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------ |
-| [Health Check](events/health-checks)                               | `check.passed`               | when a previously failing check passes                                                     |
-|                                                                          | `check.failed`               | when a previously passing check fails                                                      |
-| [Component](events/components)                                     | `component.status.<status>`  | When a component's status changes                                                          |
-
-
-## Examples
-
-```yaml title="http-check-passed.yaml"
-events:
-  - check.passed
-title: Check as {{.check.status}}
-template: 'Canary: {{.canary.name}} Message: {{.status.message}} '
-filter: "check.type == 'http'"
-person_id: d87243c9-3183-4ab9-9df9-c77c8278df11
-```
-
-```yaml title="check-failure.yaml"
-events:
-  - check.failed
-title: Check as {{.check.status}}
-template: 'Canary: {{.canary.name}} Error: {{.status.error}}'
-filter: "check.type == 'http'"
-custom_services:
-  - connection: connection://slack://<api-token>@health-check-notifications
-    name: Slack-health-checks
+```yaml title="http-check.yaml"
+---
+apiVersion: mission-control.flanksource.com/v1
+kind: Notification
+metadata:
+  name: http-check
+  namespace: default
+spec:
+  events:
+    - check.passed
+    - check.failed
+  filter: check.type == 'http'
+  to:
+    connection: connection://slack/flanksource
 ```
 
 ## Spec
 
-| Field             | Description                      | Scheme              | Required |
-| ----------------- | -------------------------------- | ------------------- | -------- |
-| `events`          | Events of notification.          | `[]string`          | `true`   |
-| `title`           | Title of notification.           | `string`            | `false`  |
-| `template`        | Template of notification.        | `string`            | `false`  |
-| `filter`          | Filter of notification.          | `string`            | `false`  |
-| `person_id`       | Person ID of notification.       | `uuid`              | `false`  |
-| `team_id`         | Team ID of notification.         | `uuid`              | `false`  |
-| `properties`      | Properties of notification.      | `map[string]string` | `false`  |
-| `custom_services` | Custom services of notification. | `JSON`              | `false`  |
-
-:::info
-    One of `person_id`, `team_id` or `custom_services` is required.
+| Field      | Description                                                        | Scheme                    | Required | Templatable |
+| ---------- | ------------------------------------------------------------------ | ------------------------- | -------- | ----------- |
+| `events`   | [List of events](./events/) that trigger this notification.        | `[]string`                | `true`   |
+| `to`       | Specify the receipients.                                           | [`Recipient`](#recipient) | `true`   |
+| `title`    | Title of the notification. [See templating](./concepts/templating) | `string`                  |          | `true`      |
+| `template` | Body of the notification. [See templating](./concepts/templating)  | `string`                  |          | `true`      |
+| `filter`   | Filter of notification.                                            | `string`                  |          |
+
+### Recipient
+
+| Field        | Description                                                      | Schema              |
+| ------------ | ---------------------------------------------------------------- | ------------------- |
+| `person`     | ID or email of the person                                        | `string`            |
+| `team`       | ID or name of the team                                           | `string`            |
+| `email`      | Email of the recipient                                           | `string`            |
+| `connection` | connection string for an external service                        | `string`            |
+| `url`        | Specify shoutrrr URL directly                                    | `string`            |
+| `properties` | Properties for Shoutrrr (applicable if shoutrrr url is provided) | `map[string]string` |
+
+:::note
+You can only specify one recipient
 :::
-
-## Supported Channels
-
-Mission control uses [Shoutrrr](https://github.com/containrrr/shoutrrr/) under the hood to deliver notifications. Most of the services in the Shoutrrr are supported. Here's the complete list:
-
-| Services    | URL Format                                                                               |
-| ----------- | ---------------------------------------------------------------------------------------- |
-| Bark        | `bark://devicekey@host`                                                                  |
-| Discord     | `discord://token@id `                                                                    |
-| Email       | `smtp://username:password@host:port/?from=fromAddress&to=recipient1[,recipient2,...]`    |
-| Gotify      | `gotify://gotify-host/token`                                                             |
-| Google Chat | `googlechat://chat.googleapis.com/v1/spaces/FOO/messages?key=bar&token=baz `             |
-| IFTTT       | `ifttt://key/?events=event1[,event2,...]&value1=value1&value2=value2&value3=value3   `   |
-| Join        | `join://shoutrrr:api-key@join/?devices=device1[,device2, ...][&icon=icon][&title=title]` |
-| Mattermost  | `mattermost://[username@]mattermost-host/token[/channel]`                                |
-| Matrix      | `matrix://username:password@host:port/[?rooms=!roomID1[,roomAlias2]] `                   |
-| Ntfy        | `ntfy://username:[email protected]/topic`                                                 |
-| OpsGenie    | `opsgenie://host/token?responders=responder1[,responder2]     `                          |
-| Pushbullet  | `pushbullet://api-token[/device/#channel/email]`                                         |
-| Pushover    | `pushover://shoutrrr:apiToken@userKey/?devices=device1[,device2, ...]`                   |
-| Rocketchat  | `rocketchat://[username@]rocketchat-host/token[/channel\| @recipient]`                   |
-| Slack       | `slack://[botname@]token-a/token-b/token-c`                                              |
-| Teams       | `teams://group@tenant/altId/groupOwner?host=organization.webhook.office.com`             |
-| Telegram    | `telegram://token@telegram?chats=@channel-1[,chat-id-1,...]`                             |
-| Zulip Chat  | `zulip://bot-mail:bot-key@zulip-domain/?stream=name-or-id&topic=name`                    |
-
-For more details please visit: [https://containrrr.dev/shoutrrr/0.8/services/overview/](https://containrrr.dev/shoutrrr/0.7/services/overview/)