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

package controllerruntime

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

Package controllerruntime provides tools to construct Kubernetes-style controllers that manipulate both Kubernetes CRDs and aggregated/built-in Kubernetes APIs.

It defines easy helpers for the common use cases when building CRDs, built on top of customizable layers of abstraction. Common cases should be easy, and uncommon cases should be possible. In general, controller-runtime tries to guide users towards Kubernetes controller best-practices.

Getting Started

The main entrypoint for controller-runtime is this root package, which contains all of the common types needed to get started building controllers:

import (
    controllers "sigs.k8s.io/controller-runtime"
)

The examples in this package walk through a basic controller setup. The kubebuilder book (https://book.kubebuilder.io) has some more in-depth walkthroughs.

controller-runtime favors structs with sane defaults over constructors, so it's fairly common to see structs being used directly in controller-runtime.

Organization

A brief-ish walkthrough of the layout of this library can be found below. Each package contains more information about how to use it.

Frequently asked questions about using controller-runtime and designing controllers can be found at https://github.com/kubernetes-sigs/controller-runtime/blob/master/FAQ.md.

Managers

Every controller and webhook is ultimately run by a Manager (pkg/manager). A manager is responsible for running controllers and webhooks, and setting up common dependencies (pkg/runtime/inject), like shared caches and clients, as well as managing leader election (pkg/leaderelection). Managers are generally configured to gracefully shut down controllers on pod termination by wiring up a signal handler (pkg/manager/signals).

Controllers

Controllers (pkg/controller) use events (pkg/events) to eventually trigger reconcile requests. They may be constructed manually, but are often constructed with a Builder (pkg/builder), which eases the wiring of event sources (pkg/source), like Kubernetes API object changes, to event handlers (pkg/handler), like "enqueue a reconcile request for the object owner". Predicates (pkg/predicate) can be used to filter which events actually trigger reconciles. There are pre-written utilities for the common cases, and interfaces and helpers for advanced cases.

Reconcilers

Controller logic is implemented in terms of Reconcilers (pkg/reconcile). A Reconciler implements a function which takes a reconcile Request containing the name and namespace of the object to reconcile, reconciles the object, and returns a Response or an error indicating whether to requeue for a second round of processing.

Clients and Caches

Reconcilers use Clients (pkg/client) to access API objects. The default client provided by the manager reads from a local shared cache (pkg/cache) and writes directly to the API server, but clients can be constructed that only talk to the API server, without a cache. The Cache will auto-populate with watched objects, as well as when other structured objects are requested. Caches may also have indexes, which can be created via a FieldIndexer (pkg/client) obtained from the manager. Indexes can used to quickly and easily look up all objects with certain fields set. Reconcilers may retrieve event recorders (pkg/recorder) to emit events using the manager.

Schemes

Clients, Caches, and many other things in Kubernetes use Schemes (pkg/scheme) to associate Go types to Kubernetes API Kinds (Group-Version-Kinds, to be specific).

Webhooks

Similarly, webhooks (pkg/webhook/admission) may be implemented directly, but are often constructed using a builder (pkg/webhook/admission/builder). They are run via a server (pkg/webhook) which is managed by a Manager.

Logging and Metrics

Logging (pkg/log) in controller-runtime is done via structured logs, using a log set of interfaces called logr (https://godoc.org/github.com/go-logr/logr). While controller-runtime provides easy setup for using Zap (https://go.uber.org/zap, pkg/log/zap), you can provide any implementation of logr as the base logger for controller-runtime.

Metrics (pkg/metrics) provided by controller-runtime are registered into a controller-runtime-specific Prometheus metrics registry. The manager can serve these by an HTTP endpoint, and additional metrics may be registered to this Registry as normal.

Testing

You can easily build integration and unit tests for your controllers and webhooks using the test Environment (pkg/envtest). This will automatically stand up a copy of etcd and kube-apiserver, and provide the correct options to connect to the API server. It's designed to work well with the Ginkgo testing framework, but should work with any testing setup.

This example creates a simple application Controller that is configured for ReplicaSets and Pods.

* Create a new application for ReplicaSets that manages Pods owned by the ReplicaSet and calls into ReplicaSetReconciler.

* Start the application. TODO(pwittrock): Update this example when we have better dependency injection support

Code:

var log = controllers.Log.WithName("builder-examples")

manager, err := controllers.NewManager(controllers.GetConfigOrDie(), controllers.Options{})
if err != nil {
    log.Error(err, "could not create manager")
    os.Exit(1)
}

err = controllers.
    NewControllerManagedBy(manager). // Create the Controller
    For(&appsv1.ReplicaSet{}).       // ReplicaSet is the Application API
    Owns(&corev1.Pod{}).             // ReplicaSet owns Pods created by it
    Complete(&ReplicaSetReconciler{Client: manager.GetClient()})
if err != nil {
    log.Error(err, "could not create controller")
    os.Exit(1)
}

if err := manager.Start(controllers.SetupSignalHandler()); err != nil {
    log.Error(err, "could not start manager")
    os.Exit(1)
}

This example creates a simple application Controller that is configured for ReplicaSets and Pods. This application controller will be running leader election with the provided configuration in the manager options. If leader election configuration is not provided, controller runs leader election with default values. Default values taken from: https://github.com/kubernetes/apiserver/blob/master/pkg/apis/config/v1alpha1/defaults.go

defaultLeaseDuration = 15 * time.Second
defaultRenewDeadline = 10 * time.Second
defaultRetryPeriod   = 2 * time.Second

* Create a new application for ReplicaSets that manages Pods owned by the ReplicaSet and calls into ReplicaSetReconciler.

* Start the application. TODO(pwittrock): Update this example when we have better dependency injection support

Code:

var log = controllers.Log.WithName("builder-examples")
leaseDuration := 100 * time.Second
renewDeadline := 80 * time.Second
retryPeriod := 20 * time.Second
manager, err := controllers.NewManager(controllers.GetConfigOrDie(), controllers.Options{
    LeaseDuration: &leaseDuration,
    RenewDeadline: &renewDeadline,
    RetryPeriod:   &retryPeriod,
})
if err != nil {
    log.Error(err, "could not create manager")
    os.Exit(1)
}

err = controllers.
    NewControllerManagedBy(manager). // Create the Controller
    For(&appsv1.ReplicaSet{}).       // ReplicaSet is the Application API
    Owns(&corev1.Pod{}).             // ReplicaSet owns Pods created by it
    Complete(&ReplicaSetReconciler{Client: manager.GetClient()})
if err != nil {
    log.Error(err, "could not create controller")
    os.Exit(1)
}

if err := manager.Start(controllers.SetupSignalHandler()); err != nil {
    log.Error(err, "could not start manager")
    os.Exit(1)
}

Index

Examples

Package Files

alias.go doc.go

Variables

var (
    // GetConfigOrDie creates a *rest.Config for talking to a Kubernetes apiserver.
    // If --kubeconfig is set, will use the kubeconfig file at that location.  Otherwise will assume running
    // in cluster and use the cluster provided kubeconfig.
    //
    // Will log an error and exit if there is an error creating the rest.Config.
    GetConfigOrDie = config.GetConfigOrDie

    // GetConfig creates a *rest.Config for talking to a Kubernetes apiserver.
    // If --kubeconfig is set, will use the kubeconfig file at that location.  Otherwise will assume running
    // in cluster and use the cluster provided kubeconfig.
    //
    // Config precedence
    //
    // * --kubeconfig flag pointing at a file
    //
    // * KUBECONFIG environment variable pointing at a file
    //
    // * In-cluster config if running in cluster
    //
    // * $HOME/.kube/config if exists
    GetConfig = config.GetConfig

    // NewControllerManagedBy returns a new controller builder that will be started by the provided Manager
    NewControllerManagedBy = builder.ControllerManagedBy

    // NewWebhookManagedBy returns a new webhook builder that will be started by the provided Manager
    NewWebhookManagedBy = builder.WebhookManagedBy

    // NewManager returns a new Manager for creating Controllers.
    NewManager = manager.New

    // CreateOrUpdate creates or updates the given object obj in the Kubernetes
    // cluster. The object's desired state should be reconciled with the existing
    // state using the passed in ReconcileFn. obj must be a struct pointer so that
    // obj can be updated with the content returned by the Server.
    //
    // It returns the executed operation and an error.
    CreateOrUpdate = controllerutil.CreateOrUpdate

    // SetControllerReference sets owner as a Controller OwnerReference on owned.
    // This is used for garbage collection of the owned object and for
    // reconciling the owner object on changes to owned (with a Watch + EnqueueRequestForOwner).
    // Since only one OwnerReference can be a controller, it returns an error if
    // there is another OwnerReference with Controller flag set.
    SetControllerReference = controllerutil.SetControllerReference

    // SetupSignalHandler registered for SIGTERM and SIGINT. A stop channel is returned
    // which is closed on one of these signals. If a second signal is caught, the program
    // is terminated with exit code 1.
    SetupSignalHandler = signals.SetupSignalHandler

    // Log is the base logger used by controller-runtime.  It delegates
    // to another logr.Logger.  You *must* call SetLogger to
    // get any actual logging.
    Log = log.Log

    // SetLogger sets a concrete logging implementation for all deferred Loggers.
    SetLogger = log.SetLogger
)

type Builder Uses

type Builder = builder.Builder

Builder builds an Application ControllerManagedBy (e.g. Operator) and returns a manager.Manager to start it.

type GroupResource Uses

type GroupResource = schema.GroupResource

GroupResource specifies a Group and a Resource, but does not force a version. This is useful for identifying concepts during lookup stages without having partially valid types

type GroupVersion Uses

type GroupVersion = schema.GroupVersion

GroupVersion contains the "group" and the "version", which uniquely identifies the API.

type Manager Uses

type Manager = manager.Manager

Manager initializes shared dependencies such as Caches and Clients, and provides them to Runnables. A Manager is required to create Controllers.

type ObjectMeta Uses

type ObjectMeta = metav1.ObjectMeta

ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.

type Options Uses

type Options = manager.Options

Options are the arguments for creating a new Manager

type Request Uses

type Request = reconcile.Request

Request contains the information necessary to reconcile a Kubernetes object. This includes the information to uniquely identify the object - its Name and Namespace. It does NOT contain information about any specific Event or the object contents itself.

type Result Uses

type Result = reconcile.Result

Result contains the result of a Reconciler invocation.

type SchemeBuilder Uses

type SchemeBuilder = scheme.Builder

SchemeBuilder builds a new Scheme for mapping go types to Kubernetes GroupVersionKinds.

type TypeMeta Uses

type TypeMeta = metav1.TypeMeta

TypeMeta describes an individual object in an API response or request with strings representing the type of the object and its API schema version. Structures that are versioned or persisted should inline TypeMeta.

+k8s:deepcopy-gen=false

Directories

PathSynopsis
examples/builtins
examples/crd
examples/crd/pkg
pkgPackage pkg provides libraries for building Controllers.
pkg/builderPackage builder provides wraps other controller-runtime libraries and exposes simple patterns for building common Controllers.
pkg/cachePackage cache provides object caches that act as caching client.Reader instances and help drive Kubernetes-object-based event handlers.
pkg/cache/informertest
pkg/cache/internal
pkg/clientPackage client contains functionality for interacting with Kubernetes API servers.
pkg/client/apiutilPackage apiutil contains utilities for working with raw Kubernetes API machinery, such as creating RESTMappers and raw REST clients, and extracting the GVK of an object.
pkg/client/configPackage config contains libraries for initializing REST configs for talking to the Kubernetes API
pkg/client/fakePackage fake provides a fake client for testing.
pkg/controllerPackage controller provides types and functions for building Controllers.
pkg/controller/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.
pkg/controller/controllerutilPackage controllerutil contains utility functions for working with and implementing Controllers.
pkg/conversionPackage conversion provides interface definitions that an API Type needs to implement for it to be supported by the generic conversion webhook handler defined under pkg/webhook/conversion.
pkg/envtestPackage envtest provides libraries for integration testing by starting a local control plane
pkg/envtest/printerPackage printer contains setup for a friendlier Ginkgo printer that's easier to parse by test automation.
pkg/eventPackage event contains the definitions for the Event types produced by source.Sources and transformed into reconcile.Requests by handler.EventHandler.
pkg/handlerPackage handler defines EventHandlers that enqueue reconcile.Requests in response to Create, Update, Deletion Events observed from Watching Kubernetes APIs.
pkg/internal/controller
pkg/internal/controller/metrics
pkg/internal/logPackage log contains utilities for fetching a new logger when one is not already available.
pkg/internal/objectutil
pkg/internal/recorder
pkg/leaderelectionPackage leaderelection contains a constructors for a leader election resource lock.
pkg/leaderelection/fakePackage fake mocks a resource lock for testing purposes.
pkg/logPackage log contains utilities for fetching a new logger when one is not already available.
pkg/log/zapPackage zap contains helpers for setting up a new logr.Logger instance using the Zap logging framework.
pkg/managerPackage manager is required to create Controllers and provides shared dependencies such as clients, caches, schemes, etc.
pkg/manager/signalsPackage signals contains libraries for handling signals to gracefully shutdown the manager in combination with Kubernetes pod graceful termination policy.
pkg/metricsPackage metrics contains controller related metrics utilities
pkg/predicatePackage predicate defines Predicates used by Controllers to filter Events before they are provided to EventHandlers.
pkg/reconcilePackage reconcile defines the Reconciler interface to implement Kubernetes APIs.
pkg/reconcile/reconciletest
pkg/recorderPackage recorder defines interfaces for working with Kubernetes event recorders.
pkg/runtimePackage runtime contains not-quite-internal mechanisms for controller-runtime, plus some deprecated exports of functionality moved elsewhere.
pkg/runtime/injectPackage inject defines interfaces and functions for propagating dependencies from a ControllerManager to the components registered with it.
pkg/runtime/logPackage log contains (deprecated) utilities for fetching a new logger when one is not already available.
pkg/runtime/schemePackage scheme contains utilities for gradually building Schemes, which contain information associating Go types with Kubernetes groups, versions, and kinds.
pkg/runtime/signalsPackage signals contains libraries for handling signals to gracefully shutdown the manager in combination with Kubernetes pod graceful termination policy.
pkg/schemePackage scheme contains utilities for gradually building Schemes, which contain information associating Go types with Kubernetes groups, versions, and kinds.
pkg/sourcePackage source provides event streams to hook up to Controllers with Controller.Watch.
pkg/source/internal
pkg/webhookPackage webhook provides methods to build and bootstrap a webhook server.
pkg/webhook/admissionPackage admission provides implementation for admission webhook and methods to implement admission webhook handlers.
pkg/webhook/conversionPackage conversion provides implementation for CRD conversion webhook that implements handler for version conversion requests for types that are convertible.
pkg/webhook/internal/certwatcher
pkg/webhook/internal/metrics

Package controllerruntime imports 10 packages (graph) and is imported by 40 packages. Updated 2019-08-23. Refresh now. Tools for package owners.