docs: Add the API spec for Events and Providers v1beta2

Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>

docs/spec/v1beta2/README.md

@@ -0,0 +1,14 @@
+# notification.toolkit.fluxcd.io/v1beta2
+
+This is the v1beta2 API specification for defining events handling and dispatching.
+
+## Specification
+
+* [Alerts](alerts.md)
+* [Events](events.md)
+* [Providers](providers.md)
+* [Receivers](receivers.md)
+
+## Go Client
+
+* [github.com/fluxcd/pkg/recorder](https://github.com/fluxcd/pkg/tree/main/recorder)

docs/spec/v1beta2/alerts.md

@@ -15,6 +15,7 @@ metadata:
   namespace: flux-system
 spec:
   type: slack
+  channel: general
   address: https://slack.com/api/chat.postMessage
   secretRef:
     name: slack-bot-token
@@ -47,7 +48,8 @@ In the above example:
 - The notification-controller starts listening for events sent for
   all GitRepositories and Kustomizations in the `flux-system` namespace.
 - When an event with severity `error` is received, the controller posts
-  a message on Slack containing the `summary` text and the reconciliation error.
+  a message on Slack channel from `.spec.channel`,
+  containing the `summary` text and the reconciliation error.
 
 You can run this example by saving the manifests into `slack-alerts.yaml`.
 
@@ -72,10 +74,17 @@ valid [DNS subdomain name](https://kubernetes.io/docs/concepts/overview/working-
 An Alert also needs a
 [`.spec` section](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#spec-and-status).
 
+### Summary
+
+`.spec.summary` is an optional field to specify a short description of the
+impact and affected cluster.
+
+The summary max length can't be greater than 255 characters. 
+
 ### Provider reference
 
 `.spec.providerRef.name` is a required field to specify a name reference to a
-Provider in the same namespace as the Alert.
+[Provider](providers.md) in the same namespace as the Alert.
 
 ### Event sources
 
@@ -142,7 +151,7 @@ To receive alerts only on errors, set the field value to `error`.
 `.spec.exclusionList` is an optional field to specify a list of regex expressions to filter
 events based on message content.
 
-### Example
+#### Example
 
 Skip alerting if the message matches a [Go regex](https://golang.org/pkg/regexp/syntax)
 from the exclusion list:
@@ -166,3 +175,9 @@ The above definition will not send alerts for transient Git clone errors like:
 ```text
 unable to clone 'ssh://git@ssh.dev.azure.com/v3/...', error: SSH could not read data: Error waiting on socket
 ```
+
+### Suspend
+
+`.spec.suspend` is an optional field to suspend the altering.
+When set to `true`, the controller will stop processing events.
+When the field is set to `false` or removed, it will resume.

docs/spec/v1beta2/events.md

@@ -0,0 +1,62 @@
+# Events
+
+The `Event` API defines the structure of the events issued by Flux controllers.
+
+Flux controllers use the [fluxcd/pkg/runtime/events](https://github.com/fluxcd/pkg/tree/main/runtime/events)
+package to push events to the notification-controller API.
+
+## Example
+
+The following is an example of an event sent by kustomize-controller to report a reconciliation error.
+
+```json
+{
+  "involvedObject": {
+    "apiVersion": "kustomize.toolkit.fluxcd.io/v1beta2",
+    "kind": "Kustomization",
+    "name": "webapp",
+    "namespace": "apps",
+    "uid": "7d0cdc51-ddcf-4743-b223-83ca5c699632"
+  },
+  "metadata": {
+    "kustomize.toolkit.fluxcd.io/revision": "main/731f7eaddfb6af01cb2173e18f0f75b0ba780ef1"
+  },
+  "severity":"error",
+  "reason": "ValidationFailed",
+  "message":"service/apps/webapp validation error: spec.type: Unsupported value: Ingress",
+  "reportingController":"kustomize-controller",
+  "timestamp":"2022-10-28T07:26:19Z"
+}
+```
+
+In the above example:
+
+- An event is issued by kustomize-controller for a specific object, indicated in the
+  `involvedObject` field.
+- The notification-controller receives the event and finds the [alerts](alerts.md)
+  that match the `involvedObject` and `severity` values.
+- For all matching alerts, the controller posts the `message` and the source revision
+  extracted from `metadata` to the alert provider API.
+
+## Event structure
+
+The Go type that defines the event structure can be found in the
+[fluxcd/pkg/runtime/events](https://github.com/fluxcd/pkg/blob/main/runtime/events/event.go)
+package.
+
+## Rate limiting
+
+Events received by notification-controller are subject to rate limiting to reduce the
+amount of duplicate alerts sent to external systems like Slack, Sentry, etc.
+
+Events are rate limited based on `involvedObject.name`, `involvedObject.namespace`,
+`involvedObject.kind`, `message`, and `metadata`.
+The interval of the rate limit is set by default to `5m` but can be configured
+with the `--rate-limit-interval` controller flag.
+
+The event server exposes HTTP request metrics to track the amount of rate limited events.
+The following promql will get the rate at which requests are rate limited:
+
+```
+rate(gotk_event_http_request_duration_seconds_count{code="429"}[30s])
+```

docs/spec/v1beta2/statusupdates.md

@@ -0,0 +1,138 @@
+# Git Commit Status Updates
+
+The notification-controller can mark Git commits as reconciled by posting
+Flux `Kustomization` events to the origin repository using Git SaaS providers APIs.
+
+## Example
+
+The following is an example of how to update the Git commit status for the GitHub repository where
+Flux was bootstrapped with `flux bootstrap github --owner=my-gh-org --repository=my-gh-repo`.
+
+```yaml
+apiVersion: notification.toolkit.fluxcd.io/v1beta2
+kind: Provider
+metadata:
+  name: github-status
+  namespace: flux-system
+spec:
+  type: github
+  address: https://github.com/my-gh-org/my-gh-repo
+  secretRef:
+    name: github-token
+---
+apiVersion: notification.toolkit.fluxcd.io/v1beta2
+kind: Alert
+metadata:
+  name: github-status
+  namespace: flux-system
+spec:
+  providerRef:
+    name: github-status
+  eventSources:
+    - kind: Kustomization
+      name: flux-system
+```
+
+In the above example:
+
+- A Provider named `github-status` is created, indicated by the
+  `Provider.metadata.name` field.
+- An Alert named `github-status` is created, indicated by the
+  `Alert.metadata.name` field.
+- The Alert references the GitHub provider, indicated by the
+  `Alert.spec.providerRef` field.
+- The notification-controller starts listening for events sent by
+  the `flux-system` Kustomization.
+- When an event is received, the controller extracts the Git commit SHA
+  from the [event](events.md) payload.
+- The controller uses the GitHub PAT from the secret indicated by the
+  `Provider.spec.secretRef.name` to authenticate with the GitHub API.
+- The controller sets the commit status to `kustomization/flux-system/<UID>`
+  followed by the success or error message from the [event](events.md) body.
+
+
+## Writing a Git commit status provider spec
+
+As with all other Kubernetes config, a Provider needs `apiVersion`,
+`kind`, and `metadata` fields. The name of an Alert object must be a
+valid [DNS subdomain name](https://kubernetes.io/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).
+A Provider also needs a
+[`.spec` section](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#spec-and-status).
+
+### Type
+
+`.spec.type` is a required field that specifies which Git SaaS vendor hosts the repository.
+
+The supported types are: `github`, `gitlab`, `bitbucket` and `azuredevops`.
+
+### Address
+
+`.spec.address` is a required field that specifies the HTTPS URL of the Git repository
+where the commits originate from.
+
+### Secret reference
+
+`.spec.secretRef.name` is a required field to specify a name reference to a
+Secret in the same namespace as the Provider, containing the authentication
+credentials for the Git SaaS API.
+
+#### GitHub authentication
+
+When `.spec.type` is set to `github`, the referenced secret must contain a key called `token` with the value set to a
+[GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token).
+
+The token must has permissions to update the commit status for the GitHub repository specified in `.spec.address`. 
+
+You can create the secret with `kubectl` like this:
+
+```shell
+kubectl create secret generic github-token --from-literal=token=<GITHUB-TOKEN>
+```
+
+#### GitLab authentication
+
+When `.spec.type` is set to `gitlab`, the referenced secret must contain a key called `token` with the value set to a
+[GitLab personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html).
+
+The token must has permissions to update the commit status for the GitLab repository specified in `.spec.address`.
+
+You can create the secret with `kubectl` like this:
+
+```shell
+kubectl create secret generic gitlab-token --from-literal=token=<GITLAB-TOKEN>
+```
+
+#### BitBucket authentication
+
+When `.spec.type` is set to `bitbucket`, the referenced secret must contain a key called `token` with the value
+set to a BitBucket username and an
+[app password](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/#Create-an-app-password)
+in the format `<username>:<app-password>`.
+
+The app password must have `Repositories (Read/Write)` permission for
+the BitBucket repository specified in `.spec.address`.
+
+You can create the secret with `kubectl` like this:
+
+```shell
+kubectl create secret generic gitlab-token --from-literal=token=<username>:<app-password>
+```
+
+#### Azure DevOps authentication
+
+When `.spec.type` is set to `azuredevops`, the referenced secret must contain a key called `token` with the value set to a
+[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 token must has permissions to update the commit status for the Azure DevOps repository specified in `.spec.address`.
+
+You can create the secret with `kubectl` like this:
+
+```shell
+kubectl create secret generic github-token --from-literal=token=<AZURE-TOKEN>
+```
+
+### Suspend
+
+`.spec.suspend` is an optional field to suspend the Git commit status updates.
+When set to `true`, the controller will stop processing events for this provider.
+When the field is set to `false` or removed, it will resume the commit status updates.