events

package
v0.115.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 29, 2026 License: Apache-2.0 Imports: 21 Imported by: 43

Documentation

Overview

Package events provides a Recorder and additional helpers to record Kubernetes Events on an external HTTP endpoint.

Testing

Controllers that embed the Recorder can test the events they emit using the helpers provided here, picking the one that matches the assertion:

  • FakeRecorder records emitted events into a channel for field-level unit assertions (Reason, Action, message, annotations) without any HTTP or apiserver dependency. Use NewNopRecorder to discard events entirely.
  • The eventstest package provides Sink, an in-process HTTP server that captures the Flux event/v1 payloads the Recorder posts to its webhook address. Point a real Recorder at Sink.URL() to assert on the payload shape actually sent to notification-controller.
  • testenv.WaitForEvents polls the apiserver for the core/v1 Events the Recorder writes, asserting they survive the round-trip. This is the only helper that catches an event silently rejected by admission (for example, a note longer than the apiserver limit on the strict events path).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type EventsAPI added in v0.115.0 

type EventsAPI string

EventsAPI selects the Kubernetes Events API the Recorder writes to. Pass a value to WithEventsAPI to override the package default. The empty value means the package default. 

const (
	// EventsAPICoreV1 writes Events through the legacy core/v1 recorder
	// (k8s.io/client-go/tools/record).
	EventsAPICoreV1 EventsAPI = "v1"

	// EventsAPIEventsV1 writes Events through the events.k8s.io/v1 recorder
	// (k8s.io/client-go/tools/events).
	EventsAPIEventsV1 EventsAPI = "events.k8s.io/v1"
)

type FakeRecorder added in v0.113.0 

type FakeRecorder struct {
	Events        chan corev1.Event
	IncludeObject bool
}

FakeRecorder is used as a fake during tests.

It was invented to be used in tests which require more precise control over e.g. assertions of specific event fields like Reason. For which string comparisons on the concentrated event message using record.FakeRecorder is not sufficient.

To empty the Events channel into a slice of the recorded events, use GetEvents(). Not initializing Events will cause the recorder to not record any messages.

The recorded corev1.Event carries the Action and Related fields the caller passed, so tests can assert on them. This is a fidelity difference from the real Recorder: its core/v1 Kubernetes Event sink has no field for either and drops them (they are preserved only on the Flux event/v1 webhook payload). The fake keeps them so unit tests can assert what the controller emitted.

func NewFakeRecorder added in v0.113.0 

func NewFakeRecorder(bufferSize int, includeObject bool) *FakeRecorder

NewFakeRecorder creates new fake event recorder with an Events channel with the given size. Setting includeObject to true will cause the recorder to include the object reference in the events.

To initialize a recorder which does not record any events, simply use: 

recorder := new(FakeRecorder)

func NewNopRecorder added in v0.113.0 

func NewNopRecorder() *FakeRecorder

NewNopRecorder creates a new FakeRecorder that doesn't record any events. This is the most lightweight option for tests that don't need event recording functionality. The recorder will implement the Recorder interface but all event calls will be no-ops.

Example: 

r := &MyReconciler{
	Client:   k8sClient,
	Recorder: events.NewNopRecorder(),
}

func (*FakeRecorder) AnnotatedEventf added in v0.113.0 

func (f *FakeRecorder) AnnotatedEventf(obj runtime.Object, related runtime.Object,
	annotations map[string]string,
	eventType, reason, action,
	message string, args ...interface{})

AnnotatedEventf emits an event with annotations.

func (*FakeRecorder) Eventf added in v0.113.0 

func (f *FakeRecorder) Eventf(obj runtime.Object, related runtime.Object, eventType, reason, action, message string, args ...interface{})

Eventf emits an event with the given message.

func (*FakeRecorder) GetEvents added in v0.113.0 

func (f *FakeRecorder) GetEvents() (events []corev1.Event)

GetEvents empties the Events channel and returns a slice of recorded events. If the Events channel is nil, it returns nil.

type Recorder 

type Recorder interface {
	// EventRecorder records events with a formatted message.
	events.EventRecorder

	// AnnotatedEventRecorder records events with annotations and a formatted message.
	events.AnnotatedEventRecorder
}

Recorder posts events to the Kubernetes API and any other event recorder webhook address, like the GitOps Toolkit notification-controller.

Use it by embedding Recorder in reconciler struct: 

import (
	...
	"k8s.io/client-go/tools/events"
	...
)

type MyTypeReconciler {
 	client.Client
	// ... etc.
	events.Recorder
}

Use NewRecorder to create a working Recorder.

func NewRecorder 

func NewRecorder(log logr.Logger, webhook, reportingController string, opts ...RecorderOption) (Recorder, error)

NewRecorder creates a Recorder with a Kubernetes event recorder and an external event recorder based on the given webhook. The recorder performs automatic retries for connection errors and 500-range response codes from the external recorder.

The scheme and Kubernetes event recorder can be provided either via WithManager (common case) or via WithScheme together with WithEventRecorder or WithLegacyEventRecorder (for tests or custom setups).

By default the Kubernetes Event backend is the legacy core/v1 recorder, which preserves the full event message. To use the events.k8s.io/v1 backend instead, pass WithEventsAPI(EventsAPIEventsV1), noting the 1024-byte note limit documented on kubeSink.

type RecorderOption added in v0.113.0 

type RecorderOption func(*recorder)

RecorderOption configures a recorder.

func WithEventRecorder added in v0.113.0 

func WithEventRecorder(er events.AnnotatedEventRecorder) RecorderOption

WithEventRecorder configures the recorder with the given events.k8s.io/v1 Kubernetes event recorder, implying EventsAPIEventsV1. Use this together with WithScheme for tests or custom setups where a ctrl.Manager is not available.

The events.k8s.io/v1 recorder is subject to the apiserver's 1024-byte note limit; see kubeSink for the trade-offs.

func WithEventsAPI added in v0.115.0 

func WithEventsAPI(api EventsAPI) RecorderOption

WithEventsAPI selects the Kubernetes Events API the recorder writes to. The empty value means the package default (core/v1). It only records the caller's choice; NewRecorder builds the backend once all options are applied. Selecting an API that conflicts with a recorder injected via WithEventRecorder or WithLegacyEventRecorder makes NewRecorder return an error.

func WithLegacyEventRecorder added in v0.115.0 

func WithLegacyEventRecorder(er kuberecorder.EventRecorder) RecorderOption

WithLegacyEventRecorder configures the recorder with the given legacy core/v1 Kubernetes event recorder (k8s.io/client-go/tools/record), implying EventsAPICoreV1. Use this together with WithScheme for tests or custom setups where a ctrl.Manager is not available.

The core/v1 recorder does not set EventTime, so recorded notes are not subject to the events.k8s.io 1024-byte limit. See kubeSink for the trade-offs.

func WithManager added in v0.113.0 

func WithManager(mgr ctrl.Manager) RecorderOption

WithManager configures the recorder with the scheme and Kubernetes Event backend from the given controller-runtime manager. The Kubernetes event recorder reports under the reportingController passed to NewRecorder.

The backend is chosen by NewRecorder once all options are applied. By default it is the legacy core/v1 recorder, which preserves the full event message. Combine with WithEventsAPI to select a different backend: 

events.WithManager(mgr)                                       // core/v1 (default)
events.WithManager(mgr), events.WithEventsAPI(events.EventsAPIEventsV1) // events.k8s.io/v1

The events.k8s.io/v1 backend records the related object and action on the Event, but the apiserver rejects notes longer than 1024 bytes (pkg/apis/core/validation.NoteLengthLimit) and silently drops the event without surfacing an error. Use it only when event messages are known to stay within the limit.

func WithRetryMax added in v0.113.0 

func WithRetryMax(n int) RecorderOption

WithRetryMax configures the maximum number of retries for the HTTP client.

func WithScheme added in v0.113.0 

func WithScheme(scheme *runtime.Scheme) RecorderOption

WithScheme configures the recorder with the given runtime scheme for resolving object references. Use this together with WithEventRecorder or WithLegacyEventRecorder for tests or custom setups where a ctrl.Manager is not available.

Source Files

View all Source files

Directories

Path Synopsis
Package eventstest provides test helpers for asserting on the events a Recorder posts to its notification webhook.
 Package eventstest provides test helpers for asserting on the events a Recorder posts to its notification webhook.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.