README

Build Status Go Report Card

Kubernetes controller-runtime Project

The Kubernetes controller-runtime Project is a set of go libraries for building Controllers.

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

Contributors:

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 alias' common functions and types to improve discoverability and reduce the number of imports for simple Controllers.

    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:
      
      

      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
      
      	// 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
      
      	// ZapLogger is a Logger implementation.
      	// If development is true, a Zap development config will be used
      	// (stacktraces on warnings, no sampling), otherwise a Zap production
      	// config will be used (stacktraces on errors, sampling).
      	ZapLogger = log.ZapLogger
      )

      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

                        Builder 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
                          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.
                          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
                          Package controllertest contains fake informers for testing controllers
                          controller/controllerutil
                          Package controllerutil contains utility functions for working with and implementing Controllers.
                          Package controllerutil contains utility functions for working with and implementing Controllers.
                          envtest
                          Package envtest provides libraries for integration testing by starting a local control plane
                          Package envtest provides libraries for integration testing by starting a local control plane
                          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.
                          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.
                          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.
                          metrics
                          Package metrics contains controller related metrics utilities
                          Package metrics contains controller related metrics utilities
                          patch
                          Package patch provides method to calculate JSON patch between 2 k8s objects.
                          Package patch provides method to calculate JSON patch between 2 k8s objects.
                          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.
                          reconcile
                          Package reconcile defines the Reconciler interface to implement Kubernetes APIs.
                          Package reconcile defines the Reconciler interface to implement Kubernetes APIs.
                          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 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.
                          runtime/signals
                          Package signals contains libraries for handling signals to shutdown the system.
                          Package signals contains libraries for handling signals to shutdown the system.
                          source
                          Package source provides event streams provided to Controllers through Controller.Watch.
                          Package source provides event streams provided to Controllers through 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/admission/builder
                          Package builder provides methods to build admission webhooks.
                          Package builder provides methods to build admission webhooks.