factory

Documentation

Index

• Constants
• Variables
• func ControllerFieldManager(controllerName, usageName string) string
• func ControllerInstanceName(instanceName, controllerName string) string
• func DefaultQueueKeysFunc(_ runtime.Object) []string
• func ObjectNameToKey(obj runtime.Object) string
• type Controller
• type EventFilterFunc
  • func NamesFilter(names ...string) EventFilterFunc
• type Factory
  • func New() *Factory
  • func (f *Factory) ResyncEvery(interval time.Duration) *Factory
  • func (f *Factory) ResyncSchedule(schedules ...string) *Factory
  • func (f *Factory) ToController(name string, eventRecorder events.Recorder) Controller
  • func (f *Factory) WithBareInformers(informers ...Informer) *Factory
  • func (f *Factory) WithControllerInstanceName(controllerInstanceName string) *Factory
  • func (f *Factory) WithFilteredEventsInformers(filter EventFilterFunc, informers ...Informer) *Factory
  • func (f *Factory) WithFilteredEventsInformersQueueKeyFunc(queueKeyFn ObjectQueueKeyFunc, filter EventFilterFunc, informers ...Informer) *Factory
  • func (f *Factory) WithFilteredEventsInformersQueueKeysFunc(queueKeyFn ObjectQueueKeysFunc, filter EventFilterFunc, informers ...Informer) *Factory
  • func (f *Factory) WithInformers(informers ...Informer) *Factory
  • func (f *Factory) WithInformersQueueKeyFunc(queueKeyFn ObjectQueueKeyFunc, informers ...Informer) *Factory
  • func (f *Factory) WithInformersQueueKeysFunc(queueKeyFn ObjectQueueKeysFunc, informers ...Informer) *Factory
  • func (f *Factory) WithNamespaceInformer(informer Informer, interestingNamespaces ...string) *Factory
  • func (f *Factory) WithPostStartHooks(hooks ...PostStartHook) *Factory
  • func (f *Factory) WithSync(syncFn SyncFunc) *Factory
  • func (f *Factory) WithSyncContext(ctx SyncContext) *Factory
  • func (f *Factory) WithSyncDegradedOnError(operatorClient operatorv1helpers.OperatorClient) *Factory
• type Informer
• type ObjectQueueKeyFunc
• type ObjectQueueKeysFunc
• type PostStartHook
• type SyncContext
  • func NewSyncContext(name string, recorder events.Recorder) SyncContext
• type SyncFunc

Constants

const DefaultQueueKey = "key"

DefaultQueueKey is the queue key used for string trigger based controllers.

Variables

var SyntheticRequeueError = errors.New("synthetic requeue request")

SyntheticRequeueError can be returned from sync() in case of forcing a sync() retry artificially. This can be also done by re-adding the key to queue, but this is cheaper and more convenient.

Functions

func ControllerFieldManager

func ControllerFieldManager(controllerName, usageName string) string

func ControllerInstanceName

func ControllerInstanceName(instanceName, controllerName string) string

func DefaultQueueKeysFunc

func DefaultQueueKeysFunc(_ runtime.Object) []string

DefaultQueueKeysFunc returns a slice with a single element - the DefaultQueueKey

func ObjectNameToKey

func ObjectNameToKey(obj runtime.Object) string

Types

type Controller

type Controller interface {
	// Run runs the controller and blocks until the controller is finished.
	// Number of workers can be specified via workers parameter.
	// This function will return when all internal loops are finished.
	// Note that having more than one worker usually means handing parallelization of Sync().
	Run(ctx context.Context, workers int)

	// Sync contain the main controller logic.
	// This should not be called directly, but can be used in unit tests to exercise the sync.
	Sync(ctx context.Context, controllerContext SyncContext) error

	// Name returns the controller name string.
	Name() string
}

Controller interface represents a runnable Kubernetes controller. Cancelling the syncContext passed will cause the controller to shutdown. Number of workers determine how much parallel the job processing should be.

type EventFilterFunc

type EventFilterFunc func(obj interface{}) bool

EventFilterFunc is used to filter informer events to prevent Sync() from being called

func NamesFilter

func NamesFilter(names ...string) EventFilterFunc

type Factory

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

Factory is generator that generate standard Kubernetes controllers. Factory is really generic and should be only used for simple controllers that does not require special stuff..

func New

func New() *Factory

New return new factory instance.

func (*Factory) ResyncEvery

func (f *Factory) ResyncEvery(interval time.Duration) *Factory

ResyncEvery will cause the Sync() function to be called periodically, regardless of informers. This is useful when you want to refresh every N minutes or you fear that your informers can be stucked. If this is not called, no periodical resync will happen. Note: The controller context passed to Sync() function in this case does not contain the object metadata or object itself.

This can be used to detect periodical resyncs, but normal Sync() have to be cautious about `nil` objects.

func (*Factory) ResyncSchedule

func (f *Factory) ResyncSchedule(schedules ...string) *Factory

ResyncSchedule allows to supply a Cron syntax schedule that will be used to schedule the sync() call runs. This allows more fine-tuned controller scheduling than ResyncEvery. Examples:

factory.New().ResyncSchedule("@every 1s").ToController() // Every second factory.New().ResyncSchedule("@hourly").ToController() // Every hour factory.New().ResyncSchedule("30 * * * *").ToController() // Every hour on the half hour

Note: The controller context passed to Sync() function in this case does not contain the object metadata or object itself.

This can be used to detect periodical resyncs, but normal Sync() have to be cautious about `nil` objects.

func (*Factory) ToController

func (f *Factory) ToController(name string, eventRecorder events.Recorder) Controller

Controller produce a runnable controller.

func (*Factory) WithBareInformers

func (f *Factory) WithBareInformers(informers ...Informer) *Factory

WithBareInformers allow to register informer that already has custom event handlers registered and no additional event handlers will be added to this informer. The controller will wait for the cache of this informer to be synced. The existing event handlers will have to respect the queue key function or the sync() implementation will have to count with custom queue keys.

func (*Factory) WithControllerInstanceName

func (f *Factory) WithControllerInstanceName(controllerInstanceName string) *Factory

WithControllerInstanceName specifies the controller instance. Useful when the same controller is used multiple times.

func (*Factory) WithFilteredEventsInformers

func (f *Factory) WithFilteredEventsInformers(filter EventFilterFunc, informers ...Informer) *Factory

WithFilteredEventsInformers is used to register event handlers and get the caches synchronized functions. Pass the informers you want to use to react to changes on resources. If informer event is observed, then the Sync() function is called. Pass filter to filter out events that should not trigger Sync() call.

func (*Factory) WithFilteredEventsInformersQueueKeyFunc

func (f *Factory) WithFilteredEventsInformersQueueKeyFunc(queueKeyFn ObjectQueueKeyFunc, filter EventFilterFunc, informers ...Informer) *Factory

WithFilteredEventsInformersQueueKeyFunc is used to register event handlers and get the caches synchronized functions. Pass informers you want to use to react to changes on resources. If informer event is observed, then the Sync() function is called. Pass the queueKeyFn you want to use to transform the informer runtime.Object into string key used by work queue. Pass filter to filter out events that should not trigger Sync() call.

func (*Factory) WithFilteredEventsInformersQueueKeysFunc

func (f *Factory) WithFilteredEventsInformersQueueKeysFunc(queueKeyFn ObjectQueueKeysFunc, filter EventFilterFunc, informers ...Informer) *Factory

WithFilteredEventsInformersQueueKeysFunc is used to register event handlers and get the caches synchronized functions. Pass informers you want to use to react to changes on resources. If informer event is observed, then the Sync() function is called. Pass the queueKeyFn you want to use to transform the informer runtime.Object into string key used by work queue. Pass filter to filter out events that should not trigger Sync() call.

func (*Factory) WithInformers

func (f *Factory) WithInformers(informers ...Informer) *Factory

WithInformers is used to register event handlers and get the caches synchronized functions. Pass informers you want to use to react to changes on resources. If informer event is observed, then the Sync() function is called.

func (*Factory) WithInformersQueueKeyFunc

func (f *Factory) WithInformersQueueKeyFunc(queueKeyFn ObjectQueueKeyFunc, informers ...Informer) *Factory

WithInformersQueueKeyFunc is used to register event handlers and get the caches synchronized functions. Pass informers you want to use to react to changes on resources. If informer event is observed, then the Sync() function is called. Pass the queueKeyFn you want to use to transform the informer runtime.Object into string key used by work queue.

func (*Factory) WithInformersQueueKeysFunc

func (f *Factory) WithInformersQueueKeysFunc(queueKeyFn ObjectQueueKeysFunc, informers ...Informer) *Factory

WithInformersQueueKeysFunc is used to register event handlers and get the caches synchronized functions. Pass informers you want to use to react to changes on resources. If informer event is observed, then the Sync() function is called. Pass the queueKeyFn you want to use to transform the informer runtime.Object into string key used by work queue.

func (*Factory) WithNamespaceInformer

func (f *Factory) WithNamespaceInformer(informer Informer, interestingNamespaces ...string) *Factory

WithNamespaceInformer is used to register event handlers and get the caches synchronized functions. The sync function will only trigger when the object observed by this informer is a namespace and its name matches the interestingNamespaces. Do not use this to register non-namespace informers.

func (*Factory) WithPostStartHooks

func (f *Factory) WithPostStartHooks(hooks ...PostStartHook) *Factory

WithPostStartHooks allows to register functions that will run asynchronously after the controller is started via Run command.

func (*Factory) WithSync

func (f *Factory) WithSync(syncFn SyncFunc) *Factory

Sync is used to set the controller synchronization function. This function is the core of the controller and is usually hold the main controller logic.

func (*Factory) WithSyncContext

func (f *Factory) WithSyncContext(ctx SyncContext) *Factory

WithSyncContext allows to specify custom, existing sync context for this factory. This is useful during unit testing where you can override the default event recorder or mock the runtime objects. If this function not called, a SyncContext is created by the factory automatically.

func (*Factory) WithSyncDegradedOnError

func (f *Factory) WithSyncDegradedOnError(operatorClient operatorv1helpers.OperatorClient) *Factory

WithSyncDegradedOnError encapsulate the controller sync() function, so when this function return an error, the operator client is used to set the degraded condition to (eg. "ControllerFooDegraded"). The degraded condition name is set based on the controller name.

type Informer

type Informer interface {
	AddEventHandler(handler cache.ResourceEventHandler) (cache.ResourceEventHandlerRegistration, error)
	HasSynced() bool
}

Informer represents any structure that allow to register event handlers and informs if caches are synced. Any SharedInformer will comply.

type ObjectQueueKeyFunc

type ObjectQueueKeyFunc func(runtime.Object) string

ObjectQueueKeyFunc is used to make a string work queue key out of the runtime object that is passed to it. This can extract the "namespace/name" if you need to or just return "key" if you building controller that only use string triggers. DEPRECATED: use ObjectQueueKeysFunc instead

type ObjectQueueKeysFunc

type ObjectQueueKeysFunc func(runtime.Object) []string

ObjectQueueKeysFunc is used to make a string work queue keys out of the runtime object that is passed to it. This can extract the "namespace/name" if you need to or just return "key" if you building controller that only use string triggers.

type PostStartHook

type PostStartHook func(ctx context.Context, syncContext SyncContext) error

PostStartHook specify a function that will run after controller is started. The context is cancelled when the controller is asked to shutdown and the post start hook should terminate as well. The syncContext allow access to controller queue and event recorder.

type SyncContext

type SyncContext interface {
	// Queue gives access to controller queue. This can be used for manual requeue, although if a Sync() function return
	// an error, the object is automatically re-queued. Use with caution.
	Queue() workqueue.RateLimitingInterface

	// QueueKey represents the queue key passed to the Sync function.
	QueueKey() string

	// Recorder provide access to event recorder.
	Recorder() events.Recorder
}

SyncContext interface represents a context given to the Sync() function where the main controller logic happen. SyncContext exposes controller name and give user access to the queue (for manual requeue). SyncContext also provides metadata about object that informers observed as changed.

func NewSyncContext

func NewSyncContext(name string, recorder events.Recorder) SyncContext

NewSyncContext gives new sync context.

type SyncFunc

type SyncFunc func(ctx context.Context, controllerContext SyncContext) error

SyncFunc is a function that contain main controller logic. The syncContext.syncContext passed is the main controller syncContext, when cancelled it means the controller is being shut down. The syncContext provides access to controller name, queue and event recorder.