docs: Add the API spec for Events and Providers v1beta2
Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>
This commit is contained in:
Stefan Prodan
Hidde Beydals
parent
ab92536f40
commit
ab5cdc8dc1
|
|
@ -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)
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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])
|
||||
```
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -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.
|
||||
Loading…
Reference in New Issue