Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update spec to reflect v1beta1 Event API #443

Merged
merged 1 commit into from
Nov 22, 2022
Merged

docs: update spec to reflect v1beta1 Event API #443

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 43 additions & 56 deletions docs/spec/v1beta1/event.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,75 +1,62 @@
# Event

The `Event` API defines what information a report of an event issued by a controller should contain.

## Specification

Spec:

```go
type Event struct {
// The object that this event is about.
// +required
InvolvedObject corev1.ObjectReference `json:"involvedObject"`

// Severity type of this event (info, error)
// +required
Severity string `json:"severity"`

// The time at which this event was recorded.
// +required
Timestamp metav1.Time `json:"timestamp"`

// A human-readable description of this event.
// Maximum length 39,000 characters
// +required
Message string `json:"message"`

// A machine understandable string that gives the reason
// for the transition into the object's current status.
// +required
Reason string `json:"reason"`

// Metadata of this event, e.g. apply change set.
// +optional
Metadata map[string]string `json:"metadata,omitempty"`

// Name of the controller that emitted this event, e.g. `source-controller`.
// +required
ReportingController string `json:"reportingController"`

// ID of the controller instance, e.g. `source-controller-xyzf`.
// +optional
ReportingInstance string `json:"reportingInstance,omitempty"`
# Events

The `Event` API defines the structure of the events issued by Flux controllers.

Flux controllers use the [`github.com/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"
}
```

Event severity:
In the above example:

```go
const (
EventSeverityInfo string = "info"
EventSeverityError string = "error"
)
```
- 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](alert.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

Controller implementations can use the [fluxcd/pkg/runtime/events](https://github.com/fluxcd/pkg/tree/main/runtime/events)
package to push events to notification-controller API.
The Go type defining the event structure can be found in the
[`github.com/fluxcd/pkg/apis/event/v1beta1`](https://github.com/fluxcd/pkg/blob/main/apis/event/v1beta1/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.revision`.
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` option.
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])
```