一文读懂K8s controller-runtime

type Controller struct {
   // Name is used to uniquely identify a Controller in tracing, logging and monitoring.  Name is required.
   Name string

   // MaxConcurrentReconciles is the maximum number of concurrent Reconciles which can be run. Defaults to 1.
   MaxConcurrentReconciles int

   // Reconciler is a function that can be called at any time with the Name / Namespace of an object and
   // ensures that the state of the system matches the state specified in the object.
   // Defaults to the DefaultReconcileFunc.
   Do reconcile.Reconciler

   // MakeQueue constructs the queue for this controller once the controller is ready to start.
   // This exists because the standard Kubernetes workqueues start themselves immediately, which
   // leads to goroutine leaks if something calls controller.New repeatedly.
   MakeQueue func() workqueue.RateLimitingInterface

   // Queue is an listeningQueue that listens for events from Informers and adds object keys to
   // the Queue for processing
   Queue workqueue.RateLimitingInterface

   // SetFields is used to inject dependencies into other objects such as Sources, EventHandlers and Predicates
   // Deprecated: the caller should handle injected fields itself.
   SetFields func(i interface{}) error

   // mu is used to synchronize Controller setup
   mu sync.Mutex

   // Started is true if the Controller has been Started
   Started bool

   // ctx is the context that was passed to Start() and used when starting watches.
   //
   // According to the docs, contexts should not be stored in a struct: https://golang.org/pkg/context,
   // while we usually always strive to follow best practices, we consider this a legacy case and it should
   // undergo a major refactoring and redesign to allow for context to not be stored in a struct.
   ctx context.Context

   // CacheSyncTimeout refers to the time limit set on waiting for cache to sync
   // Defaults to 2 minutes if not set.
   CacheSyncTimeout time.Duration

   // startWatches maintains a list of sources, handlers, and predicates to start when the controller is started.
   startWatches []watchDescription

   // LogConstructor is used to construct a logger to then log messages to users during reconciliation,
   // or for example when a watch is started.
   // Note: LogConstructor has to be able to handle nil requests as we are also using it
   // outside the context of a reconciliation.
   LogConstructor func(request *reconcile.Request) logr.Logger

   // RecoverPanic indicates whether the panic caused by reconcile should be recovered.
   RecoverPanic *bool
}

// Watch implements controller.Controller.
func (c *Controller) Watch(src source.Source, evthdler handler.EventHandler, prct ...predicate.Predicate) error {
    ...
    // Controller hasn't started yet, store the watches locally and return.
    //
    // These watches are going to be held on the controller struct until the manager or user calls Start(...).
    if !c.Started {
        c.startWatches = append(c.startWatches, watchDescription{src: src, handler: evthdler, predicates: prct})
        return nil
    }

    c.LogConstructor(nil).Info("Starting EventSource", "source", src)
    return src.Start(c.ctx, evthdler, c.Queue, prct...)
}

_, err := is.Informer.AddEventHandler(internal.EventHandler{Queue: queue, EventHandler: handler, Predicates: prct})

i, lastErr = ks.cache.GetInformer(ctx, ks.Type)
_, err := i.AddEventHandler(internal.EventHandler{Queue: queue, EventHandler: handler, Predicates: prct})

for _, watch := range c.startWatches {
   c.LogConstructor(nil).Info("Starting EventSource", "source", fmt.Sprintf("%s", watch.src))

   if err := watch.src.Start(ctx, watch.handler, c.Queue, watch.predicates...); err != nil {
      return err
   }
}

for i := 0; i < c.MaxConcurrentReconciles; i++ {
   go func() {
      defer wg.Done()
      // Run a worker thread that just dequeues items, processes them, and marks them done.
      // It enforces that the reconcileHandler is never invoked concurrently with the same object.
      for c.processNextWorkItem(ctx) {
      }
   }()
}

func (c *Controller) processNextWorkItem(ctx context.Context) bool {
    obj, shutdown := c.Queue.Get()
    if shutdown {
        // Stop working
        return false
    }

    // We call Done here so the workqueue knows we have finished
    // processing this item. We also must remember to call Forget if we
    // do not want this work item being re-queued. For example, we do
    // not call Forget if a transient error occurs, instead the item is
    // put back on the workqueue and attempted again after a back-off
    // period.
    defer c.Queue.Done(obj)

    ctrlmetrics.ActiveWorkers.WithLabelValues(c.Name).Add(1)
    defer ctrlmetrics.ActiveWorkers.WithLabelValues(c.Name).Add(-1)

    c.reconcileHandler(ctx, obj)
    return true
}

// Reconcile implements reconcile.Reconciler.
func (c *Controller) Reconcile(ctx context.Context, req reconcile.Request) (_ reconcile.Result, err error) {
    defer func() {
        if r := recover(); r != nil {
            if c.RecoverPanic != nil && *c.RecoverPanic {
                for _, fn := range utilruntime.PanicHandlers {
                    fn(r)
                }
                err = fmt.Errorf("panic: %v [recovered]", r)
                return
            }

            log := logf.FromContext(ctx)
            log.Info(fmt.Sprintf("Observed a panic in reconciler: %v", r))
            panic(r)
        }
    }()
    return c.Do.Reconcile(ctx, req)
}

type Reconciler interface {
   // Reconcile performs a full reconciliation for the object referred to by the Request.
   // The Controller will requeue the Request to be processed again if an error is non-nil or
   // Result.Requeue is true, otherwise upon completion it will remove the work from the queue.
   Reconcile(context.Context, Request) (Result, error)
}
type Request struct {
   // NamespacedName is the name and namespace of the object to reconcile.
   types.NamespacedName
}

func (c *Controller) reconcileHandler(ctx context.Context, obj interface{}) {
   // Make sure that the object is a valid request.
   req, ok := obj.(reconcile.Request)
   if !ok {
      // As the item in the workqueue is actually invalid, we call
      // Forget here else we'd go into a loop of attempting to
      // process a work item that is invalid.
      c.Queue.Forget(obj)
      c.LogConstructor(nil).Error(nil, "Queue item was not a Request", "type", fmt.Sprintf("%T", obj), "value", obj)
      // Return true, don't take a break
      return
   }
}

type EventHandler struct {
    EventHandler handler.EventHandler
    Queue        workqueue.RateLimitingInterface
    Predicates   []predicate.Predicate
}

// OnAdd creates CreateEvent and calls Create on EventHandler.
func (e EventHandler) OnAdd(obj interface{}) {
    c := event.CreateEvent{}

    // Pull Object out of the object
    if o, ok := obj.(client.Object); ok {
        c.Object = o
    } else {
        log.Error(nil, "OnAdd missing Object",
            "object", obj, "type", fmt.Sprintf("%T", obj))
        return
    }

    for _, p := range e.Predicates {
        if !p.Create(c) {
            return
        }
    }

    // Invoke create handler
    e.EventHandler.Create(c, e.Queue)
}

// Create implements EventHandler.
func (e *EnqueueRequestForObject) Create(evt event.CreateEvent, q workqueue.RateLimitingInterface) {
    if evt.Object == nil {
        enqueueLog.Error(nil, "CreateEvent received with no metadata", "event", evt)
        return
    }
    q.Add(reconcile.Request{NamespacedName: types.NamespacedName{
        Name:      evt.Object.GetName(),
        Namespace: evt.Object.GetNamespace(),
    }})
}

mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
    Scheme:                 scheme,
    MetricsBindAddress:     metricsAddr,
    Port:                   9443,
    HealthProbeBindAddress: probeAddr,
    LeaderElection:         enableLeaderElection,
    LeaderElectionID:       "9a82ee0d.my.domain",
    CertDir:                "dir",
    ...
})

if err = (&controllers.AppServiceReconciler{
    Client: mgr.GetClient(),
    Scheme: mgr.GetScheme(),
}).SetupWithManager(mgr); err != nil {
    setupLog.Error(err, "unable to create controller", "controller", "AppService")
    os.Exit(1)
}

if err := mgr.Start(ctrl.SetupSignalHandler()); err != nil {
    setupLog.Error(err, "problem running manager")
    os.Exit(1)
}

// SetupWithManager sets up the controller with the Manager.
func (r *AppServiceReconciler) SetupWithManager(mgr ctrl.Manager) error {
    return ctrl.NewControllerManagedBy(mgr).
        For(&appexamplecomv1.AppService{}).
        Complete(r)
}

NewControllerManagedBy = builder.ControllerManagedBy

func ControllerManagedBy(m manager.Manager) *Builder {
    return &Builder{mgr: m}
}

type Builder struct {
    forInput         ForInput
    ownsInput        []OwnsInput
    watchesInput     []WatchesInput
    mgr              manager.Manager
    globalPredicates []predicate.Predicate
    ctrl             controller.Controller
    ctrlOptions      controller.Options
    name             string
}

type WatchesInput struct {
    src              source.Source
    eventhandler     handler.EventHandler
    predicates       []predicate.Predicate
    objectProjection objectProjection
}

controllerName, err := blder.getControllerName(gvk, hasGVK)
blder.ctrl, err = newController(controllerName, blder.mgr, ctrlOptions)

// Add the controller as a Manager components
   return c, mgr.Add(c)
}

func (blder *Builder) doWatch() error {
    // Reconcile type
    typeForSrc, err := blder.project(blder.forInput.object, blder.forInput.objectProjection)
    if err != nil {
        return err
    }
    src := &source.Kind{Type: typeForSrc}
    hdler := &handler.EnqueueRequestForObject{}
    allPredicates := append(blder.globalPredicates, blder.forInput.predicates...)
    if err := blder.ctrl.Watch(src, hdler, allPredicates...); err != nil {
        return err
    }

    // Watches the managed types
    for _, own := range blder.ownsInput {
        typeForSrc, err := blder.project(own.object, own.objectProjection)
        if err != nil {
            return err
        }
        src := &source.Kind{Type: typeForSrc}
        hdler := &handler.EnqueueRequestForOwner{
            OwnerType:    blder.forInput.object,
            IsController: true,
        }
        allPredicates := append([]predicate.Predicate(nil), blder.globalPredicates...)
        allPredicates = append(allPredicates, own.predicates...)
        if err := blder.ctrl.Watch(src, hdler, allPredicates...); err != nil {
            return err
        }
    }

    // Do the watch requests
    for _, w := range blder.watchesInput {
        allPredicates := append([]predicate.Predicate(nil), blder.globalPredicates...)
        allPredicates = append(allPredicates, w.predicates...)

        // If the source of this watch is of type *source.Kind, project it.
        if srckind, ok := w.src.(*source.Kind); ok {
            typeForSrc, err := blder.project(srckind.Type, w.objectProjection)
            if err != nil {
                return err
            }
            srckind.Type = typeForSrc
        }

        if err := blder.ctrl.Watch(w.src, w.eventhandler, allPredicates...); err != nil {
            return err
        }
    }
    return nil
}

func (r *AppServiceReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {

    klog.Infof("开始Reconcile逻辑")
    ...
    return ctrl.Result{}, nil
}

// SetupWithManager sets up the controller with the Manager.
func (r *AppServiceReconciler) SetupWithManager(mgr ctrl.Manager) error {
    return ctrl.NewControllerManagedBy(mgr).
        Named("appServiceController").
        Watches(
            &source.Kind{
                Type: &appexamplecomv1.AppService{},
            },
            handler.Funcs{
                CreateFunc: func(createEvent event.CreateEvent, limitingInterface workqueue.RateLimitingInterface) {
                    klog.Infof("createFunc")
                    limitingInterface.Add(reconcile.Request{NamespacedName: types.NamespacedName{
                       Name:      createEvent.Object.GetName(),
                       Namespace: createEvent.Object.GetNamespace(),
                    }})
                },
                UpdateFunc: func(updateEvent event.UpdateEvent, limitingInterface workqueue.RateLimitingInterface) {
                    klog.Infof("updateFunc")
                },
                DeleteFunc: func(deleteEvent event.DeleteEvent, limitingInterface workqueue.RateLimitingInterface) {
                    klog.Infof("deleteFunc")
                },
            }).
        Complete(r)
}

func (cm *controllerManager) Start(ctx context.Context) (err error) {
    ...
    if err := cm.runnables.Webhooks.Start(cm.internalCtx); err != nil {
        if !errors.Is(err, wait.ErrWaitTimeout) {
            return err
        }
    }

    // Start and wait for caches.
    if err := cm.runnables.Caches.Start(cm.internalCtx); err != nil {
        if !errors.Is(err, wait.ErrWaitTimeout) {
            return err
        }
    }

    // Start the non-leaderelection Runnables after the cache has synced.
    if err := cm.runnables.Others.Start(cm.internalCtx); err != nil {
        if !errors.Is(err, wait.ErrWaitTimeout) {
            return err
        }
    }
    ...
}