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

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type EnqueueRequestForObject

type EnqueueRequestForObject struct{}

    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).

      Output:
      
      

      func (*EnqueueRequestForObject) Create

        Create implements EventHandler

        func (*EnqueueRequestForObject) Delete

          Delete implements EventHandler

          func (*EnqueueRequestForObject) Generic

            Generic implements EventHandler

            func (*EnqueueRequestForObject) Update

              Update implements EventHandler

              type EnqueueRequestForOwner

              type EnqueueRequestForOwner struct {
              	// OwnerType is the type of the Owner object to look for in OwnerReferences.  Only Group and Kind are compared.
              	OwnerType runtime.Object
              
              	// IsController if set will only look at the first OwnerReference with Controller: true.
              	IsController bool
              	// contains filtered or unexported fields
              }

                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 IsController 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.

                  Output:
                  
                  

                  func (*EnqueueRequestForOwner) Create

                    Create implements EventHandler

                    func (*EnqueueRequestForOwner) Delete

                      Delete implements EventHandler

                      func (*EnqueueRequestForOwner) Generic

                        Generic implements EventHandler

                        func (*EnqueueRequestForOwner) InjectMapper

                        func (e *EnqueueRequestForOwner) InjectMapper(m meta.RESTMapper) error

                          InjectMapper is called by the Controller to provide the rest mapper used by the manager.

                          func (*EnqueueRequestForOwner) InjectScheme

                          func (e *EnqueueRequestForOwner) InjectScheme(s *runtime.Scheme) error

                            InjectScheme is called by the Controller to provide a singleton scheme to the EnqueueRequestForOwner.

                            func (*EnqueueRequestForOwner) Update

                              Update implements EventHandler

                              type EnqueueRequestsFromMapFunc

                              type EnqueueRequestsFromMapFunc struct {
                              	// Mapper transforms the argument into a slice of keys to be reconciled
                              	ToRequests Mapper
                              }

                                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.

                                  Output:
                                  
                                  

                                  func (*EnqueueRequestsFromMapFunc) Create

                                    Create implements EventHandler

                                    func (*EnqueueRequestsFromMapFunc) Delete

                                      Delete implements EventHandler

                                      func (*EnqueueRequestsFromMapFunc) Generic

                                        Generic implements EventHandler

                                        func (*EnqueueRequestsFromMapFunc) InjectFunc

                                        func (e *EnqueueRequestsFromMapFunc) InjectFunc(f inject.Func) error

                                          InjectFunc implements inject.Injector.

                                          func (*EnqueueRequestsFromMapFunc) Update

                                            Update implements EventHandler

                                            type EventHandler

                                            type EventHandler interface {
                                            	// Create is called in response to an create event - e.g. Pod Creation.
                                            	Create(event.CreateEvent, workqueue.RateLimitingInterface)
                                            
                                            	// Update is called in response to an update event -  e.g. Pod Updated.
                                            	Update(event.UpdateEvent, workqueue.RateLimitingInterface)
                                            
                                            	// Delete is called in response to a delete event - e.g. Pod Deleted.
                                            	Delete(event.DeleteEvent, workqueue.RateLimitingInterface)
                                            
                                            	// 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(event.GenericEvent, workqueue.RateLimitingInterface)
                                            }

                                              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.KindSource) 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.

                                              type Funcs

                                              type Funcs struct {
                                              	// Create is called in response to an add event.  Defaults to no-op.
                                              	// RateLimitingInterface is used to enqueue reconcile.Requests.
                                              	CreateFunc func(event.CreateEvent, workqueue.RateLimitingInterface)
                                              
                                              	// Update is called in response to an update event.  Defaults to no-op.
                                              	// RateLimitingInterface is used to enqueue reconcile.Requests.
                                              	UpdateFunc func(event.UpdateEvent, workqueue.RateLimitingInterface)
                                              
                                              	// Delete is called in response to a delete event.  Defaults to no-op.
                                              	// RateLimitingInterface is used to enqueue reconcile.Requests.
                                              	DeleteFunc func(event.DeleteEvent, workqueue.RateLimitingInterface)
                                              
                                              	// GenericFunc is called in response to a generic event.  Defaults to no-op.
                                              	// RateLimitingInterface is used to enqueue reconcile.Requests.
                                              	GenericFunc func(event.GenericEvent, workqueue.RateLimitingInterface)
                                              }

                                                Funcs implements EventHandler.

                                                Example

                                                  This example implements handler.EnqueueRequestForObject.

                                                  Output:
                                                  
                                                  

                                                  func (Funcs) Create

                                                    Create implements EventHandler

                                                    func (Funcs) Delete

                                                      Delete implements EventHandler

                                                      func (Funcs) Generic

                                                        Generic implements EventHandler

                                                        func (Funcs) Update

                                                          Update implements EventHandler

                                                          type MapObject

                                                          type MapObject struct {
                                                          	// Meta is the meta data for an object from an event.
                                                          	Meta metav1.Object
                                                          
                                                          	// Object is the object from an event.
                                                          	Object runtime.Object
                                                          }

                                                            MapObject contains information from an event to be transformed into a Request.

                                                            type Mapper

                                                            type Mapper interface {
                                                            	// Map maps an object
                                                            	Map(MapObject) []reconcile.Request
                                                            }

                                                              Mapper maps an object to a collection of keys to be enqueued

                                                              type ToRequestsFunc

                                                              type ToRequestsFunc func(MapObject) []reconcile.Request

                                                                ToRequestsFunc implements Mapper using a function.

                                                                func (ToRequestsFunc) Map

                                                                  Map implements Mapper