Module events 

Publishing Kubernetes events about the resources a controller reconciles.

Events are what kubectl describe shows beneath an object, which makes them the place to explain to someone without access to the controller’s logs why an object is not converging.

An EventRecorder can be given to a Controller via with_event_recorder, in which case every failed reconciliation is published as an event on the resource being reconciled (see Context::failure_event). Reconcilers can publish events of their own through TraceMetadata::publish_event, or through EventRecorder::publish directly, which also works outside of reconciliation (for instance, from a background task).

Each controller should have its own recorder, whose Reporter names that controller, even when several controllers in a process reconcile the same kind of resource. The reporter is the only thing in an event that identifies which controller published it.

Aggregation

Publishing an event identical to the one last published for the same object, reason, and action, within SERIES_WINDOW, does not create a new event object. Instead it increments the series.count of the existing one, so that a reconciliation retrying on a backoff does not bury its resource in identical events. Any difference, including in the note, starts a new event, so that an event always describes the most recent occurrence accurately.

Failure events published by a controller additionally start afresh after the resource next reconciles successfully, so a failure that recurs after a recovery is reported as a new event rather than as a continuation of the old one.

Timeouts

Each publish is bounded by the recorder’s timeout, so that an unresponsive API server delays the reconciliation publishing an event by at most that long.

RBAC

Publishing requires create and patch permissions on events in the events.k8s.io API group, in every namespace the controller reconciles resources in. Events about cluster-scoped resources are created in the default namespace.

Structs

Event

An event to publish about a resource.

EventRecorder

Publishes Kubernetes events on resources on behalf of one controller, aggregating repeats as described in the module documentation.

Reporter

Information about the reporting controller.

Enums

EventType

The event severity or type.

PublishError

An error publishing an event.

Constants

DEFAULT_TIMEOUT

The default timeout for publishing an event.

MAX_NOTE_BYTES

The Kubernetes API server rejects events whose note is longer than this many bytes.

SERIES_WINDOW

How long after an event was last published that publishing it again still aggregates into it, rather than creating a new event.