docs: Add the API spec for Events and Providers v1beta2

Signed-off-by: Stefan Prodan <[email protected]>

Author: stefanprodan

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://[email protected]/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])
+```