package predicate

import "sigs.k8s.io/controller-runtime/pkg/predicate"

Package predicate defines Predicates used by Controllers to filter Events before they are provided to EventHandlers.

Index ¶

• type AnnotationChangedPredicate
• type Funcs
• func NewPredicateFuncs(filter func(object client.Object) bool) Funcs
• type GenerationChangedPredicate
• type LabelChangedPredicate
• type Predicate
• func LabelSelectorPredicate(s metav1.LabelSelector) (Predicate, error)
• type ResourceVersionChangedPredicate
• type TypedAnnotationChangedPredicate
• func (TypedAnnotationChangedPredicate[object]) Update(e event.TypedUpdateEvent[object]) bool
• type TypedFuncs
• func NewTypedPredicateFuncs[object any](filter func(object object) bool) TypedFuncs[object]
• func (p TypedFuncs[object]) Create(e event.TypedCreateEvent[object]) bool
• func (p TypedFuncs[object]) Delete(e event.TypedDeleteEvent[object]) bool
• func (p TypedFuncs[object]) Generic(e event.TypedGenericEvent[object]) bool
• func (p TypedFuncs[object]) Update(e event.TypedUpdateEvent[object]) bool
• type TypedGenerationChangedPredicate
• func (TypedGenerationChangedPredicate[object]) Update(e event.TypedUpdateEvent[object]) bool
• type TypedLabelChangedPredicate
• func (TypedLabelChangedPredicate[object]) Update(e event.TypedUpdateEvent[object]) bool
• type TypedPredicate
• func And[object any](predicates ...TypedPredicate[object]) TypedPredicate[object]
• func Not[object any](predicate TypedPredicate[object]) TypedPredicate[object]
• func Or[object any](predicates ...TypedPredicate[object]) TypedPredicate[object]
• type TypedResourceVersionChangedPredicate
• func (TypedResourceVersionChangedPredicate[T]) Update(e event.TypedUpdateEvent[T]) bool

Examples ¶

• Funcs

Types ¶

type AnnotationChangedPredicate ¶

type AnnotationChangedPredicate = TypedAnnotationChangedPredicate[client.Object]

AnnotationChangedPredicate implements a default update predicate function on annotation change.

This predicate will skip update events that have no change in the object's annotation. It is intended to be used in conjunction with the GenerationChangedPredicate, as in the following example:

Controller.Watch(
	&source.Kind{Type: v1.MyCustomKind},
	&handler.EnqueueRequestForObject{},
	predicate.Or(predicate.GenerationChangedPredicate{}, predicate.AnnotationChangedPredicate{}))

This is mostly useful for controllers that needs to trigger both when the resource's generation is incremented (i.e., when the resource' .spec changes), or an annotation changes (e.g., for a staging/alpha API).

type Funcs ¶

type Funcs = TypedFuncs[client.Object]

Funcs is a function that implements Predicate.

package main

import (
	"sigs.k8s.io/controller-runtime/pkg/event"
	"sigs.k8s.io/controller-runtime/pkg/predicate"
)

var p predicate.Predicate

// This example creates a new Predicate to drop Update Events where the Generation has not changed.
func main() {
	p = predicate.Funcs{
		UpdateFunc: func(e event.UpdateEvent) bool {
			return e.ObjectOld.GetGeneration() != e.ObjectNew.GetGeneration()
		},
	}
}

func NewPredicateFuncs ¶

func NewPredicateFuncs(filter func(object client.Object) bool) Funcs

NewPredicateFuncs returns a predicate funcs that applies the given filter function on CREATE, UPDATE, DELETE and GENERIC events. For UPDATE events, the filter is applied to the new object.

type GenerationChangedPredicate ¶

type GenerationChangedPredicate = TypedGenerationChangedPredicate[client.Object]

GenerationChangedPredicate implements a default update predicate function on Generation change.

This predicate will skip update events that have no change in the object's metadata.generation field. The metadata.generation field of an object is incremented by the API server when writes are made to the spec field of an object. This allows a controller to ignore update events where the spec is unchanged, and only the metadata and/or status fields are changed.

For CustomResource objects the Generation is incremented when spec is changed, or status changed and status not modeled as subresource. subresource status update will not increase Generation.

Caveats:

* The assumption that the Generation is incremented only on writing to the spec does not hold for all APIs. E.g For Deployment objects the Generation is also incremented on writes to the metadata.annotations field. For object types other than CustomResources be sure to verify which fields will trigger a Generation increment when they are written to.

* With this predicate, any update events with writes only to the status field will not be reconciled. So in the event that the status block is overwritten or wiped by someone else the controller will not self-correct to restore the correct status.

type LabelChangedPredicate ¶

type LabelChangedPredicate = TypedLabelChangedPredicate[client.Object]

LabelChangedPredicate implements a default update predicate function on label change.

This predicate will skip update events that have no change in the object's label. It is intended to be used in conjunction with the GenerationChangedPredicate, as in the following example:

Controller.Watch(

&source.Kind{Type: v1.MyCustomKind},
&handler.EnqueueRequestForObject{},
predicate.Or(predicate.GenerationChangedPredicate{}, predicate.LabelChangedPredicate{}))

This will be helpful when object's labels is carrying some extra specification information beyond object's spec, and the controller will be triggered if any valid spec change (not only in spec, but also in labels) happens.

type Predicate ¶

type Predicate = TypedPredicate[client.Object]

Predicate filters events before enqueuing the keys.

func LabelSelectorPredicate ¶

func LabelSelectorPredicate(s metav1.LabelSelector) (Predicate, error)

LabelSelectorPredicate constructs a Predicate from a LabelSelector. Only objects matching the LabelSelector will be admitted.

type ResourceVersionChangedPredicate ¶

type ResourceVersionChangedPredicate = TypedResourceVersionChangedPredicate[client.Object]

ResourceVersionChangedPredicate implements a default update predicate function on resource version change.

type TypedAnnotationChangedPredicate ¶

type TypedAnnotationChangedPredicate[object metav1.Object] struct {
	TypedFuncs[object]
}

TypedAnnotationChangedPredicate implements a default update predicate function on annotation change.

func (TypedAnnotationChangedPredicate[object]) Update ¶

func (TypedAnnotationChangedPredicate[object]) Update(e event.TypedUpdateEvent[object]) bool

Update implements default UpdateEvent filter for validating annotation change.

type TypedFuncs ¶

type TypedFuncs[object any] struct {
	// Create returns true if the Create event should be processed
	CreateFunc func(event.TypedCreateEvent[object]) bool

	// Delete returns true if the Delete event should be processed
	DeleteFunc func(event.TypedDeleteEvent[object]) bool

	// Update returns true if the Update event should be processed
	UpdateFunc func(event.TypedUpdateEvent[object]) bool

	// Generic returns true if the Generic event should be processed
	GenericFunc func(event.TypedGenericEvent[object]) bool
}

TypedFuncs is a function that implements TypedPredicate.

func NewTypedPredicateFuncs ¶

func NewTypedPredicateFuncs[object any](filter func(object object) bool) TypedFuncs[object]

NewTypedPredicateFuncs returns a predicate funcs that applies the given filter function on CREATE, UPDATE, DELETE and GENERIC events. For UPDATE events, the filter is applied to the new object.

func (TypedFuncs[object]) Create ¶

func (p TypedFuncs[object]) Create(e event.TypedCreateEvent[object]) bool

Create implements Predicate.

func (TypedFuncs[object]) Delete ¶

func (p TypedFuncs[object]) Delete(e event.TypedDeleteEvent[object]) bool

Delete implements Predicate.

func (TypedFuncs[object]) Generic ¶

func (p TypedFuncs[object]) Generic(e event.TypedGenericEvent[object]) bool

Generic implements Predicate.

func (TypedFuncs[object]) Update ¶

func (p TypedFuncs[object]) Update(e event.TypedUpdateEvent[object]) bool

Update implements Predicate.

type TypedGenerationChangedPredicate ¶

type TypedGenerationChangedPredicate[object metav1.Object] struct {
	TypedFuncs[object]
}

TypedGenerationChangedPredicate implements a default update predicate function on Generation change.

This predicate will skip update events that have no change in the object's metadata.generation field. The metadata.generation field of an object is incremented by the API server when writes are made to the spec field of an object. This allows a controller to ignore update events where the spec is unchanged, and only the metadata and/or status fields are changed.

For CustomResource objects the Generation is incremented when spec is changed, or status changed and status not modeled as subresource. subresource status update will not increase Generation.

Caveats:

* The assumption that the Generation is incremented only on writing to the spec does not hold for all APIs. E.g For Deployment objects the Generation is also incremented on writes to the metadata.annotations field. For object types other than CustomResources be sure to verify which fields will trigger a Generation increment when they are written to.

* With this predicate, any update events with writes only to the status field will not be reconciled. So in the event that the status block is overwritten or wiped by someone else the controller will not self-correct to restore the correct status.

func (TypedGenerationChangedPredicate[object]) Update ¶

func (TypedGenerationChangedPredicate[object]) Update(e event.TypedUpdateEvent[object]) bool

Update implements default UpdateEvent filter for validating generation change.

type TypedLabelChangedPredicate ¶

type TypedLabelChangedPredicate[object metav1.Object] struct {
	TypedFuncs[object]
}

TypedLabelChangedPredicate implements a default update predicate function on label change.

func (TypedLabelChangedPredicate[object]) Update ¶

func (TypedLabelChangedPredicate[object]) Update(e event.TypedUpdateEvent[object]) bool

Update implements default UpdateEvent filter for checking label change.

type TypedPredicate ¶

type TypedPredicate[object any] interface {
	// Create returns true if the Create event should be processed
	Create(event.TypedCreateEvent[object]) bool

	// Delete returns true if the Delete event should be processed
	Delete(event.TypedDeleteEvent[object]) bool

	// Update returns true if the Update event should be processed
	Update(event.TypedUpdateEvent[object]) bool

	// Generic returns true if the Generic event should be processed
	Generic(event.TypedGenericEvent[object]) bool
}

TypedPredicate filters events before enqueuing the keys.

func And ¶

func And[object any](predicates ...TypedPredicate[object]) TypedPredicate[object]

And returns a composite predicate that implements a logical AND of the predicates passed to it.

func Not ¶

func Not[object any](predicate TypedPredicate[object]) TypedPredicate[object]

Not returns a predicate that implements a logical NOT of the predicate passed to it.

func Or ¶

func Or[object any](predicates ...TypedPredicate[object]) TypedPredicate[object]

Or returns a composite predicate that implements a logical OR of the predicates passed to it.

type TypedResourceVersionChangedPredicate ¶

type TypedResourceVersionChangedPredicate[T metav1.Object] struct {
	TypedFuncs[T]
}

TypedResourceVersionChangedPredicate implements a default update predicate function on resource version change.

func (TypedResourceVersionChangedPredicate[T]) Update ¶

func (TypedResourceVersionChangedPredicate[T]) Update(e event.TypedUpdateEvent[T]) bool

Update implements default UpdateEvent filter for validating resource version change.

Source Files ¶

doc.go predicate.go