engine

package
v1.20.5 Latest Latest
Warning

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

 Go to latest Published: Feb 3, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package engine manages the lifecycle of a set of controllers.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ControllerEngine 

type ControllerEngine struct {
	// contains filtered or unexported fields
}

A ControllerEngine manages a set of controllers that can be dynamically started and stopped. It also manages a dynamic set of watches per controller, and the informers that back them.

func New 

func New(mgr manager.Manager, infs TrackingInformers, c client.Client, nc client.Client, o ...ControllerEngineOption) *ControllerEngine

New creates a new controller engine.

func (*ControllerEngine) GarbageCollectCustomResourceInformers 

func (e *ControllerEngine) GarbageCollectCustomResourceInformers(ctx context.Context) error

GarbageCollectCustomResourceInformers garbage collects informers for custom resources (e.g. Crossplane XRs, claims and composed resources) when the CRD that defines them is deleted. The garbage collector runs until the supplied context is cancelled.

func (*ControllerEngine) GetCached added in v1.18.3 

func (e *ControllerEngine) GetCached() client.Client

GetCached gets a client backed by the controller engine's cache.

func (*ControllerEngine) GetFieldIndexer 

func (e *ControllerEngine) GetFieldIndexer() client.FieldIndexer

GetFieldIndexer returns a FieldIndexer that can be used to add indexes to the controller engine's cache.

func (*ControllerEngine) GetUncached added in v1.18.3 

func (e *ControllerEngine) GetUncached() client.Client

GetUncached gets a non-cached client.

func (*ControllerEngine) GetWatches 

func (e *ControllerEngine) GetWatches(name string) ([]WatchID, error)

GetWatches returns the active watches for the supplied controller.

func (*ControllerEngine) IsRunning 

func (e *ControllerEngine) IsRunning(name string) bool

IsRunning returns true if the named controller is running.

func (*ControllerEngine) Start 

func (e *ControllerEngine) Start(name string, o ...ControllerOption) error

Start a new controller.

func (*ControllerEngine) StartWatches 

func (e *ControllerEngine) StartWatches(ctx context.Context, name string, ws ...Watch) error

StartWatches instructs the named controller to start the supplied watches. The controller will only start a watch if it's not already watching the type of object specified by the supplied Watch. StartWatches blocks other operations on the same controller if and when it starts a watch.

func (*ControllerEngine) Stop 

func (e *ControllerEngine) Stop(ctx context.Context, name string) error

Stop a controller.

func (*ControllerEngine) StopWatches 

func (e *ControllerEngine) StopWatches(ctx context.Context, name string, ws ...WatchID) (int, error)

StopWatches stops the supplied watches. StopWatches blocks other operations on the same controller if and when it stops a watch. It returns the number of watches that it successfully stopped.

type ControllerEngineOption 

type ControllerEngineOption func(*ControllerEngine)

A ControllerEngineOption configures a controller engine.

func WithLogger 

func WithLogger(l logging.Logger) ControllerEngineOption

WithLogger configures an Engine to use a logger.

func WithMetrics added in v1.20.0 

func WithMetrics(m Metrics) ControllerEngineOption

WithMetrics configures an Engine to expose metrics.

type ControllerOption 

type ControllerOption func(o *ControllerOptions)

A ControllerOption configures a controller.

func WithNewControllerFn 

func WithNewControllerFn(fn NewControllerFn) ControllerOption

WithNewControllerFn configures how the engine starts a new controller-runtime controller.

func WithRuntimeOptions 

func WithRuntimeOptions(ko kcontroller.Options) ControllerOption

WithRuntimeOptions configures the underlying controller-runtime controller.

func WithWatchGarbageCollector 

func WithWatchGarbageCollector(gc WatchGarbageCollector) ControllerOption

WithWatchGarbageCollector specifies an optional garbage collector this controller should use to remove unused watches.

type ControllerOptions 

type ControllerOptions struct {
	// contains filtered or unexported fields
}

ControllerOptions configure a controller.

type EventHandler 

type EventHandler struct {
	// contains filtered or unexported fields
}

An EventHandler converts a controller-runtime handler and predicates into a client-go ResourceEventHandler. It's a stripped down version of controller-runtime's internal implementation. https://github.com/kubernetes-sigs/controller-runtime/blob/v0.18.2/pkg/internal/source/event_handler.go#L35

func NewEventHandler 

func NewEventHandler(ctx context.Context, q workqueue.TypedRateLimitingInterface[reconcile.Request], h handler.EventHandler, ps ...predicate.Predicate) *EventHandler

NewEventHandler creates a new EventHandler.

func (*EventHandler) HandlerFuncs 

func (e *EventHandler) HandlerFuncs() kcache.ResourceEventHandlerFuncs

HandlerFuncs converts EventHandler to a ResourceEventHandlerFuncs.

func (*EventHandler) OnAdd 

func (e *EventHandler) OnAdd(obj any)

OnAdd creates CreateEvent and calls Create on EventHandler.

func (*EventHandler) OnDelete 

func (e *EventHandler) OnDelete(obj any)

OnDelete creates DeleteEvent and calls Delete on EventHandler.

func (*EventHandler) OnUpdate 

func (e *EventHandler) OnUpdate(oldObj, newObj any)

OnUpdate creates UpdateEvent and calls Update on EventHandler.

type InformerTrackingCache 

type InformerTrackingCache struct {
	// The wrapped cache.
	cache.Cache
	// contains filtered or unexported fields
}

An InformerTrackingCache wraps a cache.Cache and keeps track of what GVKs it has started informers for. It takes a blocking lock whenever a new informer is started or stopped, but so does the standard controller-runtime Cache implementation.

func TrackInformers 

func TrackInformers(c cache.Cache, s *runtime.Scheme) *InformerTrackingCache

TrackInformers wraps the supplied cache, adding a method to query which informers are active.

func (*InformerTrackingCache) ActiveInformers 

func (c *InformerTrackingCache) ActiveInformers() []schema.GroupVersionKind

ActiveInformers returns the GVKs of the informers believed to currently be active. The InformerTrackingCache considers an informer to become active when a caller calls Get, List, or one of the GetInformer methods. It considers an informer to become inactive when a caller calls the RemoveInformer method.

func (*InformerTrackingCache) Get 

func (c *InformerTrackingCache) Get(ctx context.Context, key client.ObjectKey, obj client.Object, opts ...client.GetOption) error

Get retrieves an obj for the given object key from the Kubernetes Cluster. obj must be a struct pointer so that obj can be updated with the response returned by the Server.

Getting an object marks the informer for the object's GVK active.

func (*InformerTrackingCache) GetInformer 

func (c *InformerTrackingCache) GetInformer(ctx context.Context, obj client.Object, opts ...cache.InformerGetOption) (cache.Informer, error)

GetInformer fetches or constructs an informer for the given object that corresponds to a single API kind and resource.

Getting an informer for an object marks the informer as active.

func (*InformerTrackingCache) GetInformerForKind 

func (c *InformerTrackingCache) GetInformerForKind(ctx context.Context, gvk schema.GroupVersionKind, opts ...cache.InformerGetOption) (cache.Informer, error)

GetInformerForKind is similar to GetInformer, except that it takes a group-version-kind, instead of the underlying object.

Getting an informer marks the informer as active.

func (*InformerTrackingCache) List 

func (c *InformerTrackingCache) List(ctx context.Context, list client.ObjectList, opts ...client.ListOption) error

List retrieves list of objects for a given namespace and list options. On a successful call, Items field in the list will be populated with the result returned from the server.

Listing objects marks the informer for the object's GVK active.

func (*InformerTrackingCache) RemoveInformer 

func (c *InformerTrackingCache) RemoveInformer(ctx context.Context, obj client.Object) error

RemoveInformer removes an informer entry and stops it if it was running.

Removing an informer marks the informer as inactive.

type Metrics added in v1.20.0 

type Metrics interface {
	// ControllerStarted records a controller start.
	ControllerStarted(name string)

	// ControllerStopped records a controller stop.
	ControllerStopped(name string)

	// WatchStarted records a watch start for a controller.
	WatchStarted(name string, t WatchType)

	// WatchStopped records a watch stop for a controller.
	WatchStopped(name string, t WatchType)
}

Metrics for the controller engine.

type NewControllerFn 

type NewControllerFn func(name string, mgr manager.Manager, options kcontroller.Options) (kcontroller.Controller, error)

A NewControllerFn can start a new controller-runtime controller.

type NopMetrics added in v1.20.0 

type NopMetrics struct{}

NopMetrics does nothing.

func (*NopMetrics) ControllerStarted added in v1.20.0 

func (m *NopMetrics) ControllerStarted(_ string)

ControllerStarted does nothing.

func (*NopMetrics) ControllerStopped added in v1.20.0 

func (m *NopMetrics) ControllerStopped(_ string)

ControllerStopped does nothing.

func (*NopMetrics) WatchStarted added in v1.20.0 

func (m *NopMetrics) WatchStarted(_ string, _ WatchType)

WatchStarted does nothing.

func (*NopMetrics) WatchStopped added in v1.20.0 

func (m *NopMetrics) WatchStopped(_ string, _ WatchType)

WatchStopped does nothing.

type PrometheusMetrics added in v1.20.0 

type PrometheusMetrics struct {
	// contains filtered or unexported fields
}

PrometheusMetrics for the controller engine.

func NewPrometheusMetrics added in v1.20.0 

func NewPrometheusMetrics() *PrometheusMetrics

NewPrometheusMetrics exposes controller engine metrics via Prometheus.

func (*PrometheusMetrics) Collect added in v1.20.0 

func (m *PrometheusMetrics) Collect(ch chan<- prometheus.Metric)

Collect is called by the Prometheus registry when collecting metrics. The implementation sends each collected metric via the provided channel and returns once the last metric has been sent.

func (*PrometheusMetrics) ControllerStarted added in v1.20.0 

func (m *PrometheusMetrics) ControllerStarted(name string)

ControllerStarted records a controller start.

func (*PrometheusMetrics) ControllerStopped added in v1.20.0 

func (m *PrometheusMetrics) ControllerStopped(name string)

ControllerStopped records a controller stop.

func (*PrometheusMetrics) Describe added in v1.20.0 

func (m *PrometheusMetrics) Describe(ch chan<- *prometheus.Desc)

Describe sends the super-set of all possible descriptors of metrics collected by this Collector to the provided channel and returns once the last descriptor has been sent.

func (*PrometheusMetrics) WatchStarted added in v1.20.0 

func (m *PrometheusMetrics) WatchStarted(name string, t WatchType)

WatchStarted records a watch start for a controller.

func (*PrometheusMetrics) WatchStopped added in v1.20.0 

func (m *PrometheusMetrics) WatchStopped(name string, t WatchType)

WatchStopped records a watch stop for a controller.

type StoppableSource 

type StoppableSource struct {
	// contains filtered or unexported fields
}

A StoppableSource is a controller-runtime watch source that can be stopped.

func NewStoppableSource 

func NewStoppableSource(inf cache.Informer, h handler.EventHandler, ps ...predicate.Predicate) *StoppableSource

NewStoppableSource returns a new watch source that can be stopped.

func (*StoppableSource) Start 

func (s *StoppableSource) Start(ctx context.Context, q workqueue.TypedRateLimitingInterface[reconcile.Request]) error

Start is internal and should be called only by the Controller to register an EventHandler with the Informer to enqueue reconcile.Requests.

func (*StoppableSource) Stop 

func (s *StoppableSource) Stop(_ context.Context) error

Stop removes the EventHandler from the source's Informer. The Informer will stop sending events to the source.

type TrackingInformers 

type TrackingInformers interface {
	cache.Informers
	ActiveInformers() []schema.GroupVersionKind
}

TrackingInformers is a set of Informers. It tracks which are active.

type Watch 

type Watch struct {
	// contains filtered or unexported fields
}

Watch an object.

func WatchFor 

func WatchFor(kind client.Object, wt WatchType, h handler.EventHandler, p ...predicate.Predicate) Watch

WatchFor returns a Watch for the supplied kind of object. Events will be handled by the supplied EventHandler, and may be filtered by the supplied predicates.

type WatchGarbageCollector 

type WatchGarbageCollector interface {
	GarbageCollectWatches(ctx context.Context, interval time.Duration)
}

A WatchGarbageCollector periodically garbage collects watches.

type WatchID 

type WatchID struct {
	Type WatchType
	GVK  schema.GroupVersionKind
}

A WatchID uniquely identifies a watch.

type WatchType 

type WatchType string

A WatchType uniquely identifies a "type" of watch - i.e. a handler and a set of predicates. The controller engine uniquely identifies a Watch by its (kind, watch type) tuple. The engine will only start one watch of each (kind, watch type) tuple. To watch the same kind of resource multiple times, use different watch types. 

const (
	WatchTypeClaim               WatchType = "Claim"
	WatchTypeCompositeResource   WatchType = "CompositeResource"
	WatchTypeComposedResource    WatchType = "ComposedResource"
	WatchTypeCompositionRevision WatchType = "CompositionRevision"
)

Common watch types.

Source Files

View all Source files

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.