README

Go Report Card

Kubernetes controller-runtime Project

The Kubernetes controller-runtime Project is a set of go libraries for building Controllers. It is leveraged by Kubebuilder and Operator SDK. Both are a great place to start for new projects. See Kubebuilder's Quick Start to see how it can be used.

Documentation:

Versioning, Maintenance, and Compatibility

The full documentation can be found at VERSIONING.md, but TL;DR:

Users:

  • We follow Semantic Versioning (semver)
  • Use releases with your dependency management to ensure that you get compatible code
  • The master branch contains all the latest code, some of which may break compatibility (so "normal" go get is not recommended)

Contributors:

FAQ

See FAQ.md

Community, discussion, contribution, and support

Learn how to engage with the Kubernetes community on the community page.

controller-runtime is a subproject of the kubebuilder project in sig apimachinery.

You can reach the maintainers of this project at:

Contributing

Contributions are greatly appreciated. The maintainers actively manage the issues list, and try to highlight issues suitable for newcomers. The project follows the typical GitHub pull request model. See CONTRIBUTING.md for more details. Before starting any work, please either comment on an existing issue, or file a new one.

Code of conduct

Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct.

Expand ▾ Collapse ▴

Documentation

Overview

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. The default split client does not promise to invalidate the cache during writes (nor does it promise sequential create/get coherence), and code should not assume a get immediately following a create/update will return the updated resource. 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.

Example

    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

    Output:
    
    
    Example (UpdateLeaderElectionDurations)

      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

      Output:
      
      

      Index

      Examples

      Constants

      This section is empty.

      Variables

      View Source
      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
      )

      Functions

      This section is empty.

      Types

      type Builder

      type Builder = builder.Builder

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

        type GroupResource

        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

          type GroupVersion = schema.GroupVersion

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

            type Manager

            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

              type ObjectMeta = metav1.ObjectMeta

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

                type Options

                type Options = manager.Options

                  Options are the arguments for creating a new Manager

                  type Request

                  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

                    type Result = reconcile.Result

                      Result contains the result of a Reconciler invocation.

                      type SchemeBuilder

                      type SchemeBuilder = scheme.Builder

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

                        type TypeMeta

                        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

                          Source Files

                          Directories

                          Path Synopsis
                          examples
                          crd
                          crd/pkg
                          +kubebuilder:object:generate=true +groupName=chaosapps.metamagical.io
                          +kubebuilder:object:generate=true +groupName=chaosapps.metamagical.io
                          scratch-env Module
                          pkg
                          Package pkg provides libraries for building Controllers.
                          Package pkg provides libraries for building Controllers.
                          builder
                          Package builder provides wraps other controller-runtime libraries and exposes simple patterns for building common Controllers.
                          Package builder provides wraps other controller-runtime libraries and exposes simple patterns for building common Controllers.
                          cache
                          Package cache provides object caches that act as caching client.Reader instances and help drive Kubernetes-object-based event handlers.
                          Package cache provides object caches that act as caching client.Reader instances and help drive Kubernetes-object-based event handlers.
                          client
                          Package client contains functionality for interacting with Kubernetes API servers.
                          Package client contains functionality for interacting with Kubernetes API servers.
                          client/apiutil
                          Package 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.
                          Package 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.
                          client/config
                          Package config contains libraries for initializing REST configs for talking to the Kubernetes API
                          Package config contains libraries for initializing REST configs for talking to the Kubernetes API
                          client/fake
                          Package fake provides a fake client for testing.
                          Package fake provides a fake client for testing.
                          controller
                          Package controller provides types and functions for building Controllers.
                          Package controller provides types and functions for building Controllers.
                          controller/controllertest
                          Package 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.
                          Package 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.
                          controller/controllerutil
                          Package controllerutil contains utility functions for working with and implementing Controllers.
                          Package controllerutil contains utility functions for working with and implementing Controllers.
                          conversion
                          Package 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.
                          Package 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.
                          envtest
                          Package envtest provides libraries for integration testing by starting a local control plane Control plane binaries (etcd and kube-apiserver) are loaded by default from /usr/local/kubebuilder/bin.
                          Package envtest provides libraries for integration testing by starting a local control plane Control plane binaries (etcd and kube-apiserver) are loaded by default from /usr/local/kubebuilder/bin.
                          envtest/printer
                          Package printer contains setup for a friendlier Ginkgo printer that's easier to parse by test automation.
                          Package printer contains setup for a friendlier Ginkgo printer that's easier to parse by test automation.
                          event
                          Package event contains the definitions for the Event types produced by source.Sources and transformed into reconcile.Requests by handler.EventHandler.
                          Package event contains the definitions for the Event types produced by source.Sources and transformed into reconcile.Requests by handler.EventHandler.
                          handler
                          Package handler defines EventHandlers that enqueue reconcile.Requests in response to Create, Update, Deletion Events observed from Watching Kubernetes APIs.
                          Package handler defines EventHandlers that enqueue reconcile.Requests in response to Create, Update, Deletion Events observed from Watching Kubernetes APIs.
                          healthz
                          Package healthz contains helpers from supporting liveness and readiness endpoints.
                          Package healthz contains helpers from supporting liveness and readiness endpoints.
                          leaderelection
                          Package leaderelection contains a constructors for a leader election resource lock.
                          Package leaderelection contains a constructors for a leader election resource lock.
                          leaderelection/fake
                          Package fake mocks a resource lock for testing purposes.
                          Package fake mocks a resource lock for testing purposes.
                          log
                          Package log contains utilities for fetching a new logger when one is not already available.
                          Package log contains utilities for fetching a new logger when one is not already available.
                          log/zap
                          Package zap contains helpers for setting up a new logr.Logger instance using the Zap logging framework.
                          Package zap contains helpers for setting up a new logr.Logger instance using the Zap logging framework.
                          manager
                          Package manager is required to create Controllers and provides shared dependencies such as clients, caches, schemes, etc.
                          Package manager is required to create Controllers and provides shared dependencies such as clients, caches, schemes, etc.
                          manager/signals
                          Package signals contains libraries for handling signals to gracefully shutdown the manager in combination with Kubernetes pod graceful termination policy.
                          Package signals contains libraries for handling signals to gracefully shutdown the manager in combination with Kubernetes pod graceful termination policy.
                          metrics
                          Package metrics contains controller related metrics utilities
                          Package metrics contains controller related metrics utilities
                          patterns/application
                          Package application documents patterns for building Controllers to manage specific applications.
                          Package application documents patterns for building Controllers to manage specific applications.
                          patterns/operator
                          Package operator serves to redirect users to the application package.
                          Package operator serves to redirect users to the application package.
                          predicate
                          Package predicate defines Predicates used by Controllers to filter Events before they are provided to EventHandlers.
                          Package predicate defines Predicates used by Controllers to filter Events before they are provided to EventHandlers.
                          ratelimiter
                          Package ratelimiter defines rate limiters used by Controllers to limit how frequently requests may be queued.
                          Package ratelimiter defines rate limiters used by Controllers to limit how frequently requests may be queued.
                          reconcile
                          Package reconcile defines the Reconciler interface to implement Kubernetes APIs.
                          Package reconcile defines the Reconciler interface to implement Kubernetes APIs.
                          recorder
                          Package recorder defines interfaces for working with Kubernetes event recorders.
                          Package recorder defines interfaces for working with Kubernetes event recorders.
                          runtime
                          Package runtime contains not-quite-internal mechanisms for controller-runtime, plus some deprecated exports of functionality moved elsewhere.
                          Package runtime contains not-quite-internal mechanisms for controller-runtime, plus some deprecated exports of functionality moved elsewhere.
                          runtime/inject
                          Package inject defines interfaces and functions for propagating dependencies from a ControllerManager to the components registered with it.
                          Package inject defines interfaces and functions for propagating dependencies from a ControllerManager to the components registered with it.
                          runtime/log
                          Package log contains (deprecated) utilities for fetching a new logger when one is not already available.
                          Package log contains (deprecated) utilities for fetching a new logger when one is not already available.
                          runtime/scheme
                          Package scheme contains utilities for gradually building Schemes, which contain information associating Go types with Kubernetes groups, versions, and kinds.
                          Package scheme contains utilities for gradually building Schemes, which contain information associating Go types with Kubernetes groups, versions, and kinds.
                          runtime/signals
                          Package signals contains libraries for handling signals to gracefully shutdown the manager in combination with Kubernetes pod graceful termination policy.
                          Package signals contains libraries for handling signals to gracefully shutdown the manager in combination with Kubernetes pod graceful termination policy.
                          scheme
                          Package scheme contains utilities for gradually building Schemes, which contain information associating Go types with Kubernetes groups, versions, and kinds.
                          Package scheme contains utilities for gradually building Schemes, which contain information associating Go types with Kubernetes groups, versions, and kinds.
                          source
                          Package source provides event streams to hook up to Controllers with Controller.Watch.
                          Package source provides event streams to hook up to Controllers with Controller.Watch.
                          webhook
                          Package webhook provides methods to build and bootstrap a webhook server.
                          Package webhook provides methods to build and bootstrap a webhook server.
                          webhook/admission
                          Package admission provides implementation for admission webhook and methods to implement admission webhook handlers.
                          Package admission provides implementation for admission webhook and methods to implement admission webhook handlers.
                          webhook/conversion
                          Package conversion provides implementation for CRD conversion webhook that implements handler for version conversion requests for types that are convertible.
                          Package conversion provides implementation for CRD conversion webhook that implements handler for version conversion requests for types that are convertible.