controller-runtime: sigs.k8s.io/controller-runtime/pkg/controller Index | Examples | Files | Directories

package controller

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

Package controller provides types and functions for building Controllers. Controllers implement Kubernetes APIs.

Creation

To create a new Controller, first create a manager.Manager and pass it to the controller.New function. The Controller MUST be started by calling Manager.Start.

Index

Examples

Package Files

controller.go doc.go

type Controller Uses

type Controller interface {
    // Reconciler is called to reconcile an object by Namespace/Name
    reconcile.Reconciler

    // Watch takes events provided by a Source and uses the EventHandler to
    // enqueue reconcile.Requests in response to the events.
    //
    // Watch may be provided one or more Predicates to filter events before
    // they are given to the EventHandler.  Events will be passed to the
    // EventHandler if all provided Predicates evaluate to true.
    Watch(src source.Source, eventhandler handler.EventHandler, predicates ...predicate.Predicate) error

    // Start starts the controller.  Start blocks until stop is closed or a
    // controller has an error starting.
    Start(stop <-chan struct{}) error
}

Controller implements a Kubernetes API. A Controller manages a work queue fed reconcile.Requests from source.Sources. Work is performed through the reconcile.Reconciler for each enqueued item. Work typically is reads and writes Kubernetes objects to make the system state match the state specified in the object Spec.

This example starts a new Controller named "pod-controller" to Watch Pods and call a no-op Reconciler.

Code:

// mgr is a manager.Manager

// Create a new Controller that will call the provided Reconciler function in response
// to events.
c, err := controller.New("pod-controller", mgr, controller.Options{
    Reconciler: reconcile.Func(func(o reconcile.Request) (reconcile.Result, error) {
        // Your business logic to implement the API by creating, updating, deleting objects goes here.
        return reconcile.Result{}, nil
    }),
})
if err != nil {
    log.Error(err, "unable to create pod-controller")
    os.Exit(1)
}

// Watch for Pod create / update / delete events and call Reconcile
err = c.Watch(&source.Kind{Type: &corev1.Pod{}}, &handler.EnqueueRequestForObject{})
if err != nil {
    log.Error(err, "unable to watch pods")
    os.Exit(1)
}

// Start the Controller through the manager.
if err := mgr.Start(signals.SetupSignalHandler()); err != nil {
    log.Error(err, "unable to continue running manager")
    os.Exit(1)
}

This example starts a new Controller named "pod-controller" to Watch Pods with the unstructured object and call a no-op Reconciler.

Code:

// mgr is a manager.Manager

// Create a new Controller that will call the provided Reconciler function in response
// to events.
c, err := controller.New("pod-controller", mgr, controller.Options{
    Reconciler: reconcile.Func(func(o reconcile.Request) (reconcile.Result, error) {
        // Your business logic to implement the API by creating, updating, deleting objects goes here.
        return reconcile.Result{}, nil
    }),
})
if err != nil {
    log.Error(err, "unable to create pod-controller")
    os.Exit(1)
}

u := &unstructured.Unstructured{}
u.SetGroupVersionKind(schema.GroupVersionKind{
    Kind:    "Pod",
    Group:   "",
    Version: "v1",
})
// Watch for Pod create / update / delete events and call Reconcile
err = c.Watch(&source.Kind{Type: u}, &handler.EnqueueRequestForObject{})
if err != nil {
    log.Error(err, "unable to watch pods")
    os.Exit(1)
}

// Start the Controller through the manager.
if err := mgr.Start(signals.SetupSignalHandler()); err != nil {
    log.Error(err, "unable to continue running manager")
    os.Exit(1)
}

func New Uses

func New(name string, mgr manager.Manager, options Options) (Controller, error)

New returns a new Controller registered with the Manager. The Manager will ensure that shared Caches have been synced before the Controller is Started.

This example creates a new Controller named "pod-controller" with a no-op reconcile function. The manager.Manager will be used to Start the Controller, and will provide it a shared Cache and Client.

Code:

_, err := controller.New("pod-controller", mgr, controller.Options{
    Reconciler: reconcile.Func(func(o reconcile.Request) (reconcile.Result, error) {
        // Your business logic to implement the API by creating, updating, deleting objects goes here.
        return reconcile.Result{}, nil
    }),
})
if err != nil {
    log.Error(err, "unable to create pod-controller")
    os.Exit(1)
}

func NewUnmanaged Uses

func NewUnmanaged(name string, mgr manager.Manager, options Options) (Controller, error)

NewUnmanaged returns a new controller without adding it to the manager. The caller is responsible for starting the returned controller.

This example creates a new controller named "pod-controller" to watch Pods and call a no-op reconciler. The controller is not added to the provided manager, and must thus be started and stopped by the caller.

Code:

// mgr is a manager.Manager

// Configure creates a new controller but does not add it to the supplied
// manager.
c, err := controller.NewUnmanaged("pod-controller", mgr, controller.Options{
    Reconciler: reconcile.Func(func(_ reconcile.Request) (reconcile.Result, error) {
        return reconcile.Result{}, nil
    }),
})
if err != nil {
    log.Error(err, "unable to create pod-controller")
    os.Exit(1)
}

if err := c.Watch(&source.Kind{Type: &corev1.Pod{}}, &handler.EnqueueRequestForObject{}); err != nil {
    log.Error(err, "unable to watch pods")
    os.Exit(1)
}

// Create a stop channel for our controller. The controller will stop when
// this channel is closed.
stop := make(chan struct{})

// Start our controller in a goroutine so that we do not block.
go func() {
    // Block until our controller manager is elected leader. We presume our
    // entire process will terminate if we lose leadership, so we don't need
    // to handle that.
    <-mgr.Elected()

    // Start our controller. This will block until the stop channel is
    // closed, or the controller returns an error.
    if err := c.Start(stop); err != nil {
        log.Error(err, "cannot run experiment controller")
    }
}()

// Stop our controller.
close(stop)

type Options Uses

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

    // Reconciler reconciles an object
    Reconciler reconcile.Reconciler

    // RateLimiter is used to limit how frequently requests may be queued.
    // Defaults to MaxOfRateLimiter which has both overall and per-item rate limiting.
    // The overall is a token bucket and the per-item is exponential.
    RateLimiter ratelimiter.RateLimiter
}

Options are the arguments for creating a new Controller

Directories

PathSynopsis
controllertestPackage controllertest contains fake informers for testing controllers When in doubt, it's almost always better to test against a real API server using envtest.Environment.
controllerutilPackage controllerutil contains utility functions for working with and implementing Controllers.

Package controller imports 10 packages (graph) and is imported by 502 packages. Updated 2020-06-20. Refresh now. Tools for package owners.