Skip to content

Commit

Permalink
docs: update alert provider types
Browse files Browse the repository at this point in the history 
Signed-off-by: Moshe Immerman <moshe@flanksource.com>
  • Loading branch information
@moshloop
moshloop committed Feb 2, 2022
1 parent 402e029 commit d8808ef
Showing 1 changed file with 67 additions and 65 deletions.
132 changes: 67 additions & 65 deletions docs/spec/v1beta1/provider.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,81 +8,85 @@ Spec:

```go
type ProviderSpec struct {
// Type of provider
// +kubebuilder:validation:Enum=slack;discord;msteams;rocket;generic;github;gitlab;bitbucket;azuredevops;googlechat;webex;sentry;azureeventhub;telegram;lark;matrix;opsgenie
// +required
Type string `json:"type"`

// Alert channel for this provider
// +optional
Channel string `json:"channel,omitempty"`

// Bot username for this provider
// +optional
Username string `json:"username,omitempty"`

// HTTP/S webhook address of this provider
// +kubebuilder:validation:Pattern="^(http|https)://"
// +optional
Address string `json:"address,omitempty"`

// HTTP/S address of the proxy
// +kubebuilder:validation:Pattern="^(http|https)://"
// +optional
Proxy string `json:"proxy,omitempty"`

// Secret reference containing the provider webhook URL
// +optional
SecretRef *meta.LocalObjectReference `json:"secretRef,omitempty"`

// CertSecretRef can be given the name of a secret containing
// a PEM-encoded CA certificate (`caFile`)
// +optional
CertSecretRef *meta.LocalObjectReference `json:"certSecretRef,omitempty"`
// Type of provider
// +kubebuilder:validation:Enum=slack;discord;msteams;rocket;generic;github;gitlab;bitbucket;azuredevops;googlechat;webex;sentry;azureeventhub;telegram;lark;matrix;opsgenie
// +required
Type string `json:"type"`

// Alert channel for this provider
// +optional
Channel string `json:"channel,omitempty"`

// Bot username for this provider
// +optional
Username string `json:"username,omitempty"`

// HTTP/S webhook address of this provider
// +kubebuilder:validation:Pattern="^(http|https)://"
// +optional
Address string `json:"address,omitempty"`

// HTTP/S address of the proxy
// +kubebuilder:validation:Pattern="^(http|https)://"
// +optional
Proxy string `json:"proxy,omitempty"`

// Secret reference containing the provider details, valid key names are: address, token, headers (YAML encoded)
// +optional
SecretRef *meta.LocalObjectReference `json:"secretRef,omitempty"`

// CertSecretRef can be given the name of a secret containing
// a PEM-encoded CA certificate (`caFile`)
// +optional
CertSecretRef *meta.LocalObjectReference `json:"certSecretRef,omitempty"`
}
```

Notification providers:

* Slack
* Discord
* Microsoft Teams
* Rocket
* Google Chat
* Webex
* Sentry
* Telegram
* Lark
* Matrix
* Azure Event Hub
* Generic webhook
* Opsgenie
* Alertmanager
| Provider | Type |
| --------------- | ------------- |
| Alertmanager | alertmanager |
| Azure Event Hub | azureeventhub |
| Discord | discord |
| Generic webhook | generic |
| Google Chat | googlechat |
| Lark | lark |
| Matrix | matrix |
| Microsoft Teams | msteams |
| Opsgenie | opsgenie |
| Rocket | rocket |
| Sentry | sentry |
| Slack | slack |
| Telegram | telegram |
| WebEx | webex |

Git commit status providers:

* GitHub
* GitLab
* Bitbucket
* Azure DevOps
| Provider | Type |
| ------------ | ----------- |
| Azure DevOps | azuredevops |
| Bitbucket | bitbucket |
| GitHub | github |
| GitLab | gitlab |

Status:

```go
// ProviderStatus defines the observed state of Provider
type ProviderStatus struct {
// +optional
Conditions []Condition `json:"conditions,omitempty"`
// +optional
Conditions []Condition `json:"conditions,omitempty"`
}
```

Status condition types:

```go
const (
// ReadyCondition represents the fact that a given object has passed
// validation and was acknowledge by the controller.
ReadyCondition string = "Ready"
// ReadyCondition represents the fact that a given object has passed
// validation and was acknowledge by the controller.
ReadyCondition string = "Ready"
)
```

Expand Down Expand Up @@ -175,7 +179,7 @@ metadata:
spec:
type: generic
address: https://api.github.com/repos/owner/repo/dispatches
secretRef:
secretRef:
name: generic-secret
---
apiVersion: v1
Expand Down Expand Up @@ -233,7 +237,7 @@ and use `https://api.telegram.org/` as the api url.
--from-literal=address=https://api.telegram.org
```

Also note that `spec.channel` can be a unique identifier for the target chat
Also note that `spec.channel` can be a unique identifier for the target chat
or username of the target channel (in the format @channelusername)

```yaml
Expand All @@ -255,6 +259,7 @@ For Matrix, the address is the homeserver URL and the token is the access token
returned by a call to `/login` or `/register`.

Create a secret:

```
kubectl create secret generic matrix-token \
--from-literal=token=<access-token> \
Expand Down Expand Up @@ -303,7 +308,6 @@ spec:
name: lark-token
```


### Opsgenie

For sending notifications to Opsgenie, you will have to
Expand Down Expand Up @@ -332,7 +336,6 @@ spec:
name: opsgenie-token
```


### Prometheus Alertmanager

Sends notifications to [alertmanager v2 api](https://github.com/prometheus/alertmanager/blob/main/api/v2/openapi.yaml) if alert manager has basic authentication configured it is recommended to use
Expand All @@ -355,7 +358,6 @@ If a summary is provided in the alert resource an additional "summary" annotatio

The provider will send the following labels for the event.


| Label | Description |
| ----------- | -------------------------------------------------------------------------------------------------- |
| alertname | The string Flux followed by the Kind and the reason for the event e.g FluxKustomizationProgressing |
Expand All @@ -366,7 +368,6 @@ The provider will send the following labels for the event.
| name | The name of the involved object associated with the event |
| namespace | The namespace of the involved object associated with the event |


### Slack App

It is possible to use a Slack App bot integration to send messages. To obtain a bot token, follow
Expand All @@ -375,7 +376,7 @@ It is possible to use a Slack App bot integration to send messages. To obtain a
Differences from the Slack [webhook method](#notifications):

* Possible to use single credentials to post to different channels (by adding the integration to each channel)
* All messages are posted with the app username, and not the name of the controller (e.g. `helm-controller, `source-controller`)
* All messages are posted with the app username, and not the name of the controller (e.g. `helm-controller,`source-controller`)

To enable the Slack App, the secret must contain the URL of the [chat.postMessage](https://api.slack.com/methods/chat.postMessage)
method and your Slack bot token (starts with `xoxb-`):
Expand Down Expand Up @@ -404,7 +405,6 @@ spec:
name: slack-token
```


### Git commit status

The GitHub, GitLab, Bitbucket, and Azure DevOps provider will write to the
Expand Down Expand Up @@ -436,6 +436,7 @@ For bitbucket, the token should contain the username and [app password](https://
in the format `<username>:<password>`. The app password should have `Repositories (Read/Write)` permission.

You can create the secret using this command:

```shell
kubectl create secret generic api-token --from-literal=token=<username>:<app-password>
```
Expand All @@ -444,9 +445,9 @@ kubectl create secret generic api-token --from-literal=token=<username>:<app-pas

GitHub. GitLab, and Azure DevOps use personal access tokens to authenticate with their API:

- [GitHub personal access token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token)
- [GitLab personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)
- [Azure DevOps personal access token](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=preview-page)
* [GitHub personal access token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token)
* [GitLab personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)
* [Azure DevOps personal access token](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=preview-page)

The providers require a secret in the same format, with the personal access token as the value for the token key:

Expand Down Expand Up @@ -487,6 +488,7 @@ metadata:
data:
token: <api-key>
```

### Azure Event Hub

The Azure Event Hub supports two authentication methods, [JWT](https://docs.microsoft.com/en-us/azure/event-hubs/authenticate-application)
Expand Down

0 comments on commit d8808ef

Please sign in to comment.