handler

Documentation

Overview

Package handler defines EventHandlers that enqueue reconcile.Requests in response to Create, Update, Deletion Events observed from Watching Kubernetes APIs. Users should provide a source.Source and handler.EventHandler to Controller.Watch in order to generate and enqueue reconcile.Request work items.

Generally, following premade event handlers should be sufficient for most use cases:

EventHandlers:

EnqueueRequestForObject - Enqueues a reconcile.Request containing the Name and Namespace of the object in the Event. This will cause the object that was the source of the Event (e.g. the created / deleted / updated object) to be reconciled.

EnqueueRequestForOwner - Enqueues a reconcile.Request containing the Name and Namespace of the Owner of the object in the Event. This will cause owner of the object that was the source of the Event (e.g. the owner object that created the object) to be reconciled.

EnqueueRequestsFromMapFunc - Enqueues reconcile.Requests resulting from a user provided transformation function run against the object in the Event. This will cause an arbitrary collection of objects (defined from a transformation of the source object) to be reconciled.

Index

• type EnqueueRequestForObject
• type EventHandler
  • func EnqueueRequestForOwner(scheme *runtime.Scheme, mapper meta.RESTMapper, ownerType client.Object, ...) EventHandler
  • func EnqueueRequestsFromMapFunc(fn MapFunc) EventHandler
• type Funcs
• type MapFunc
• type OwnerOption
  • func OnlyControllerOwner() OwnerOption
• type TypedEnqueueRequestForObject
  • func (e *TypedEnqueueRequestForObject[T]) Create(ctx context.Context, evt event.TypedCreateEvent[T], ...)
  • func (e *TypedEnqueueRequestForObject[T]) Delete(ctx context.Context, evt event.TypedDeleteEvent[T], ...)
  • func (e *TypedEnqueueRequestForObject[T]) Generic(ctx context.Context, evt event.TypedGenericEvent[T], ...)
  • func (e *TypedEnqueueRequestForObject[T]) Update(ctx context.Context, evt event.TypedUpdateEvent[T], ...)
• type TypedEventHandler
  • func TypedEnqueueRequestForOwner[object client.Object](scheme *runtime.Scheme, mapper meta.RESTMapper, ownerType client.Object, ...) TypedEventHandler[object, reconcile.Request]
  • func TypedEnqueueRequestsFromMapFunc[object any, request comparable](fn TypedMapFunc[object, request]) TypedEventHandler[object, request]
• type TypedFuncs
  • func (h TypedFuncs[object, request]) Create(ctx context.Context, e event.TypedCreateEvent[object], ...)
  • func (h TypedFuncs[object, request]) Delete(ctx context.Context, e event.TypedDeleteEvent[object], ...)
  • func (h TypedFuncs[object, request]) Generic(ctx context.Context, e event.TypedGenericEvent[object], ...)
  • func (h TypedFuncs[object, request]) Update(ctx context.Context, e event.TypedUpdateEvent[object], ...)
• type TypedMapFunc

Examples

• EnqueueRequestForObject
• EnqueueRequestForOwner
• EnqueueRequestsFromMapFunc
• Funcs

Types

type EnqueueRequestForObject

type EnqueueRequestForObject = TypedEnqueueRequestForObject[client.Object]

EnqueueRequestForObject enqueues a Request containing the Name and Namespace of the object that is the source of the Event. (e.g. the created / deleted / updated objects Name and Namespace). handler.EnqueueRequestForObject is used by almost all Controllers that have associated Resources (e.g. CRDs) to reconcile the associated Resource.

Example

This example watches Pods and enqueues Requests with the Name and Namespace of the Pod from the Event (i.e. change caused by a Create, Update, Delete).

package main

import (
	corev1 "k8s.io/api/core/v1"
	"sigs.k8s.io/controller-runtime/pkg/controller"
	"sigs.k8s.io/controller-runtime/pkg/handler"
	"sigs.k8s.io/controller-runtime/pkg/manager"
	"sigs.k8s.io/controller-runtime/pkg/source"
)

var (
	mgr manager.Manager
	c   controller.Controller
)

func main() {
	// controller is a controller.controller
	err := c.Watch(
		source.Kind(mgr.GetCache(), &corev1.Pod{}, &handler.TypedEnqueueRequestForObject[*corev1.Pod]{}),
	)
	if err != nil {
		// handle it
	}
}

type EventHandler

type EventHandler = TypedEventHandler[client.Object, reconcile.Request]

EventHandler enqueues reconcile.Requests in response to events (e.g. Pod Create). EventHandlers map an Event for one object to trigger Reconciles for either the same object or different objects - e.g. if there is an Event for object with type Foo (using source.Kind) then reconcile one or more object(s) with type Bar.

Identical reconcile.Requests will be batched together through the queuing mechanism before reconcile is called.

* Use EnqueueRequestForObject to reconcile the object the event is for - do this for events for the type the Controller Reconciles. (e.g. Deployment for a Deployment Controller)

* Use EnqueueRequestForOwner to reconcile the owner of the object the event is for - do this for events for the types the Controller creates. (e.g. ReplicaSets created by a Deployment Controller)

* Use EnqueueRequestsFromMapFunc to transform an event for an object to a reconcile of an object of a different type - do this for events for types the Controller may be interested in, but doesn't create. (e.g. If Foo responds to cluster size events, map Node events to Foo objects.)

Unless you are implementing your own EventHandler, you can ignore the functions on the EventHandler interface. Most users shouldn't need to implement their own EventHandler.

func EnqueueRequestForOwner

func EnqueueRequestForOwner(scheme *runtime.Scheme, mapper meta.RESTMapper, ownerType client.Object, opts ...OwnerOption) EventHandler

EnqueueRequestForOwner enqueues Requests for the Owners of an object. E.g. the object that created the object that was the source of the Event.

If a ReplicaSet creates Pods, users may reconcile the ReplicaSet in response to Pod Events using:

- a source.Kind Source with Type of Pod.

- a handler.enqueueRequestForOwner EventHandler with an OwnerType of ReplicaSet and OnlyControllerOwner set to true.

Example

This example watches ReplicaSets and enqueues a Request containing the Name and Namespace of the owning (direct) Deployment responsible for the creation of the ReplicaSet.

package main

import (
	appsv1 "k8s.io/api/apps/v1"
	"sigs.k8s.io/controller-runtime/pkg/controller"
	"sigs.k8s.io/controller-runtime/pkg/handler"
	"sigs.k8s.io/controller-runtime/pkg/manager"
	"sigs.k8s.io/controller-runtime/pkg/source"
)

var (
	mgr manager.Manager
	c   controller.Controller
)

func main() {
	// controller is a controller.controller
	err := c.Watch(
		source.Kind(mgr.GetCache(),
			&appsv1.ReplicaSet{},
			handler.TypedEnqueueRequestForOwner[*appsv1.ReplicaSet](mgr.GetScheme(), mgr.GetRESTMapper(), &appsv1.Deployment{}, handler.OnlyControllerOwner()),
		),
	)
	if err != nil {
		// handle it
	}
}

func EnqueueRequestsFromMapFunc

func EnqueueRequestsFromMapFunc(fn MapFunc) EventHandler

EnqueueRequestsFromMapFunc enqueues Requests by running a transformation function that outputs a collection of reconcile.Requests on each Event. The reconcile.Requests may be for an arbitrary set of objects defined by some user specified transformation of the source Event. (e.g. trigger Reconciler for a set of objects in response to a cluster resize event caused by adding or deleting a Node)

EnqueueRequestsFromMapFunc is frequently used to fan-out updates from one object to one or more other objects of a differing type.

For UpdateEvents which contain both a new and old object, the transformation function is run on both objects and both sets of Requests are enqueue.

Example

This example watches Deployments and enqueues a Request contain the Name and Namespace of different objects (of Type: MyKind) using a mapping function defined by the user.

package main

import (
	"context"

	appsv1 "k8s.io/api/apps/v1"
	"k8s.io/apimachinery/pkg/types"
	"sigs.k8s.io/controller-runtime/pkg/controller"
	"sigs.k8s.io/controller-runtime/pkg/handler"
	"sigs.k8s.io/controller-runtime/pkg/manager"
	"sigs.k8s.io/controller-runtime/pkg/reconcile"
	"sigs.k8s.io/controller-runtime/pkg/source"
)

var (
	mgr manager.Manager
	c   controller.Controller
)

func main() {
	// controller is a controller.controller
	err := c.Watch(
		source.Kind(mgr.GetCache(), &appsv1.Deployment{},
			handler.TypedEnqueueRequestsFromMapFunc(func(ctx context.Context, a *appsv1.Deployment) []reconcile.Request {
				return []reconcile.Request{
					{NamespacedName: types.NamespacedName{
						Name:      a.Name + "-1",
						Namespace: a.Namespace,
					}},
					{NamespacedName: types.NamespacedName{
						Name:      a.Name + "-2",
						Namespace: a.Namespace,
					}},
				}
			}),
		),
	)
	if err != nil {
		// handle it
	}
}

type Funcs

type Funcs = TypedFuncs[client.Object, reconcile.Request]

Funcs implements eventhandler.

Example

This example implements handler.EnqueueRequestForObject.

package main

import (
	"context"

	corev1 "k8s.io/api/core/v1"
	"k8s.io/apimachinery/pkg/types"
	"k8s.io/client-go/util/workqueue"
	"sigs.k8s.io/controller-runtime/pkg/controller"
	"sigs.k8s.io/controller-runtime/pkg/event"
	"sigs.k8s.io/controller-runtime/pkg/handler"
	"sigs.k8s.io/controller-runtime/pkg/manager"
	"sigs.k8s.io/controller-runtime/pkg/reconcile"
	"sigs.k8s.io/controller-runtime/pkg/source"
)

var (
	mgr manager.Manager
	c   controller.Controller
)

func main() {
	// controller is a controller.controller
	err := c.Watch(
		source.Kind(mgr.GetCache(), &corev1.Pod{},
			handler.TypedFuncs[*corev1.Pod, reconcile.Request]{
				CreateFunc: func(ctx context.Context, e event.TypedCreateEvent[*corev1.Pod], q workqueue.TypedRateLimitingInterface[reconcile.Request]) {
					q.Add(reconcile.Request{NamespacedName: types.NamespacedName{
						Name:      e.Object.Name,
						Namespace: e.Object.Namespace,
					}})
				},
				UpdateFunc: func(ctx context.Context, e event.TypedUpdateEvent[*corev1.Pod], q workqueue.TypedRateLimitingInterface[reconcile.Request]) {
					q.Add(reconcile.Request{NamespacedName: types.NamespacedName{
						Name:      e.ObjectNew.Name,
						Namespace: e.ObjectNew.Namespace,
					}})
				},
				DeleteFunc: func(ctx context.Context, e event.TypedDeleteEvent[*corev1.Pod], q workqueue.TypedRateLimitingInterface[reconcile.Request]) {
					q.Add(reconcile.Request{NamespacedName: types.NamespacedName{
						Name:      e.Object.Name,
						Namespace: e.Object.Namespace,
					}})
				},
				GenericFunc: func(ctx context.Context, e event.TypedGenericEvent[*corev1.Pod], q workqueue.TypedRateLimitingInterface[reconcile.Request]) {
					q.Add(reconcile.Request{NamespacedName: types.NamespacedName{
						Name:      e.Object.Name,
						Namespace: e.Object.Namespace,
					}})
				},
			},
		),
	)
	if err != nil {
		// handle it
	}
}

type MapFunc

type MapFunc = TypedMapFunc[client.Object, reconcile.Request]

MapFunc is the signature required for enqueueing requests from a generic function. This type is usually used with EnqueueRequestsFromMapFunc when registering an event handler.

type OwnerOption

type OwnerOption func(e enqueueRequestForOwnerInterface)

OwnerOption modifies an EnqueueRequestForOwner EventHandler.

func OnlyControllerOwner

func OnlyControllerOwner() OwnerOption

OnlyControllerOwner if provided will only look at the first OwnerReference with Controller: true.

type TypedEnqueueRequestForObject

type TypedEnqueueRequestForObject[object client.Object] struct{}

TypedEnqueueRequestForObject enqueues a Request containing the Name and Namespace of the object that is the source of the Event. (e.g. the created / deleted / updated objects Name and Namespace). handler.TypedEnqueueRequestForObject is used by almost all Controllers that have associated Resources (e.g. CRDs) to reconcile the associated Resource.

TypedEnqueueRequestForObject is experimental and subject to future change.

func (*TypedEnqueueRequestForObject[T]) Create

func (e *TypedEnqueueRequestForObject[T]) Create(ctx context.Context, evt event.TypedCreateEvent[T], q workqueue.TypedRateLimitingInterface[reconcile.Request])

Create implements EventHandler.

func (*TypedEnqueueRequestForObject[T]) Delete

func (e *TypedEnqueueRequestForObject[T]) Delete(ctx context.Context, evt event.TypedDeleteEvent[T], q workqueue.TypedRateLimitingInterface[reconcile.Request])

Delete implements EventHandler.

func (*TypedEnqueueRequestForObject[T]) Generic

func (e *TypedEnqueueRequestForObject[T]) Generic(ctx context.Context, evt event.TypedGenericEvent[T], q workqueue.TypedRateLimitingInterface[reconcile.Request])

Generic implements EventHandler.

func (*TypedEnqueueRequestForObject[T]) Update

func (e *TypedEnqueueRequestForObject[T]) Update(ctx context.Context, evt event.TypedUpdateEvent[T], q workqueue.TypedRateLimitingInterface[reconcile.Request])

Update implements EventHandler.

type TypedEventHandler

type TypedEventHandler[object any, request comparable] interface {
	// Create is called in response to a create event - e.g. Pod Creation.
	Create(context.Context, event.TypedCreateEvent[object], workqueue.TypedRateLimitingInterface[request])

	// Update is called in response to an update event -  e.g. Pod Updated.
	Update(context.Context, event.TypedUpdateEvent[object], workqueue.TypedRateLimitingInterface[request])

	// Delete is called in response to a delete event - e.g. Pod Deleted.
	Delete(context.Context, event.TypedDeleteEvent[object], workqueue.TypedRateLimitingInterface[request])

	// Generic is called in response to an event of an unknown type or a synthetic event triggered as a cron or
	// external trigger request - e.g. reconcile Autoscaling, or a Webhook.
	Generic(context.Context, event.TypedGenericEvent[object], workqueue.TypedRateLimitingInterface[request])
}

TypedEventHandler enqueues reconcile.Requests in response to events (e.g. Pod Create). TypedEventHandlers map an Event for one object to trigger Reconciles for either the same object or different objects - e.g. if there is an Event for object with type Foo (using source.Kind) then reconcile one or more object(s) with type Bar.

Identical reconcile.Requests will be batched together through the queuing mechanism before reconcile is called.

* Use TypedEnqueueRequestForObject to reconcile the object the event is for - do this for events for the type the Controller Reconciles. (e.g. Deployment for a Deployment Controller)

* Use TypedEnqueueRequestForOwner to reconcile the owner of the object the event is for - do this for events for the types the Controller creates. (e.g. ReplicaSets created by a Deployment Controller)

* Use TypedEnqueueRequestsFromMapFunc to transform an event for an object to a reconcile of an object of a different type - do this for events for types the Controller may be interested in, but doesn't create. (e.g. If Foo responds to cluster size events, map Node events to Foo objects.)

Unless you are implementing your own TypedEventHandler, you can ignore the functions on the TypedEventHandler interface. Most users shouldn't need to implement their own TypedEventHandler.

TypedEventHandler is experimental and subject to future change.

func TypedEnqueueRequestForOwner

func TypedEnqueueRequestForOwner[object client.Object](scheme *runtime.Scheme, mapper meta.RESTMapper, ownerType client.Object, opts ...OwnerOption) TypedEventHandler[object, reconcile.Request]

TypedEnqueueRequestForOwner enqueues Requests for the Owners of an object. E.g. the object that created the object that was the source of the Event.

If a ReplicaSet creates Pods, users may reconcile the ReplicaSet in response to Pod Events using:

- a source.Kind Source with Type of Pod.

- a handler.typedEnqueueRequestForOwner EventHandler with an OwnerType of ReplicaSet and OnlyControllerOwner set to true.

TypedEnqueueRequestForOwner is experimental and subject to future change.

func TypedEnqueueRequestsFromMapFunc

func TypedEnqueueRequestsFromMapFunc[object any, request comparable](fn TypedMapFunc[object, request]) TypedEventHandler[object, request]

TypedEnqueueRequestsFromMapFunc enqueues Requests by running a transformation function that outputs a collection of reconcile.Requests on each Event. The reconcile.Requests may be for an arbitrary set of objects defined by some user specified transformation of the source Event. (e.g. trigger Reconciler for a set of objects in response to a cluster resize event caused by adding or deleting a Node)

TypedEnqueueRequestsFromMapFunc is frequently used to fan-out updates from one object to one or more other objects of a differing type.

For TypedUpdateEvents which contain both a new and old object, the transformation function is run on both objects and both sets of Requests are enqueue.

TypedEnqueueRequestsFromMapFunc is experimental and subject to future change.

type TypedFuncs

type TypedFuncs[object any, request comparable] struct {
	// Create is called in response to an add event.  Defaults to no-op.
	// RateLimitingInterface is used to enqueue reconcile.Requests.
	CreateFunc func(context.Context, event.TypedCreateEvent[object], workqueue.TypedRateLimitingInterface[request])

	// Update is called in response to an update event.  Defaults to no-op.
	// RateLimitingInterface is used to enqueue reconcile.Requests.
	UpdateFunc func(context.Context, event.TypedUpdateEvent[object], workqueue.TypedRateLimitingInterface[request])

	// Delete is called in response to a delete event.  Defaults to no-op.
	// RateLimitingInterface is used to enqueue reconcile.Requests.
	DeleteFunc func(context.Context, event.TypedDeleteEvent[object], workqueue.TypedRateLimitingInterface[request])

	// GenericFunc is called in response to a generic event.  Defaults to no-op.
	// RateLimitingInterface is used to enqueue reconcile.Requests.
	GenericFunc func(context.Context, event.TypedGenericEvent[object], workqueue.TypedRateLimitingInterface[request])
}

TypedFuncs implements eventhandler.

TypedFuncs is experimental and subject to future change.

func (TypedFuncs[object, request]) Create

func (h TypedFuncs[object, request]) Create(ctx context.Context, e event.TypedCreateEvent[object], q workqueue.TypedRateLimitingInterface[request])

Create implements EventHandler.

func (TypedFuncs[object, request]) Delete

func (h TypedFuncs[object, request]) Delete(ctx context.Context, e event.TypedDeleteEvent[object], q workqueue.TypedRateLimitingInterface[request])

Delete implements EventHandler.

func (TypedFuncs[object, request]) Generic

func (h TypedFuncs[object, request]) Generic(ctx context.Context, e event.TypedGenericEvent[object], q workqueue.TypedRateLimitingInterface[request])

Generic implements EventHandler.

func (TypedFuncs[object, request]) Update

func (h TypedFuncs[object, request]) Update(ctx context.Context, e event.TypedUpdateEvent[object], q workqueue.TypedRateLimitingInterface[request])

Update implements EventHandler.

type TypedMapFunc

type TypedMapFunc[object any, request comparable] func(context.Context, object) []request

TypedMapFunc is the signature required for enqueueing requests from a generic function. This type is usually used with EnqueueRequestsFromTypedMapFunc when registering an event handler.

TypedMapFunc is experimental and subject to future change.