From d8808efcb3e1bf3c5a38492616c0084d25fb9621 Mon Sep 17 00:00:00 2001 From: Moshe Immerman Date: Wed, 2 Feb 2022 15:48:50 +0200 Subject: [PATCH] docs: update alert provider types Signed-off-by: Moshe Immerman --- docs/spec/v1beta1/provider.md | 132 +++++++++++++++++----------------- 1 file changed, 67 insertions(+), 65 deletions(-) diff --git a/docs/spec/v1beta1/provider.md b/docs/spec/v1beta1/provider.md index 107c9288e..61865ca60 100644 --- a/docs/spec/v1beta1/provider.md +++ b/docs/spec/v1beta1/provider.md @@ -8,71 +8,75 @@ 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"` } ``` @@ -80,9 +84,9 @@ 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" ) ``` @@ -175,7 +179,7 @@ metadata: spec: type: generic address: https://api.github.com/repos/owner/repo/dispatches - secretRef: + secretRef: name: generic-secret --- apiVersion: v1 @@ -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 @@ -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= \ @@ -303,7 +308,6 @@ spec: name: lark-token ``` - ### Opsgenie For sending notifications to Opsgenie, you will have to @@ -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 @@ -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 | @@ -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 @@ -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-`): @@ -404,7 +405,6 @@ spec: name: slack-token ``` - ### Git commit status The GitHub, GitLab, Bitbucket, and Azure DevOps provider will write to the @@ -436,6 +436,7 @@ For bitbucket, the token should contain the username and [app password](https:// in the format `:`. 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=: ``` @@ -444,9 +445,9 @@ kubectl create secret generic api-token --from-literal=token=: ``` + ### Azure Event Hub The Azure Event Hub supports two authentication methods, [JWT](https://docs.microsoft.com/en-us/azure/event-hubs/authenticate-application)