controllerruntime · pkg.go.dev

README

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:

All code PR must be labeled with 🐛 (patch fixes), ✨ (backwards-compatible features), or ⚠️ (breaking changes)
Breaking changes will find their way into the next major release, other changes will go into an semi-immediate patch or minor release
For a quick PR template suggesting the right information, use one of these PR templates:

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:

Slack channel: #kubebuilder
Google Group: kubebuilder@googlegroups.com

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

package main

import (
	"context"
	"fmt"
	"os"

	appsv1 "k8s.io/api/apps/v1"
	corev1 "k8s.io/api/core/v1"
	controllers "sigs.k8s.io/controller-runtime"
	"sigs.k8s.io/controller-runtime/pkg/client"
)

// 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
func main() {
	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)
	}
}

// ReplicaSetReconciler is a simple Controller example implementation.
type ReplicaSetReconciler struct {
	client.Client
}

// Implement the business logic:
// This function will be called when there is a change to a ReplicaSet or a Pod with an OwnerReference
// to a ReplicaSet.
//
// * Read the ReplicaSet
// * Read the Pods
// * Set a Label on the ReplicaSet with the Pod count
func (a *ReplicaSetReconciler) Reconcile(req controllers.Request) (controllers.Result, error) {
	// Read the ReplicaSet
	rs := &appsv1.ReplicaSet{}
	err := a.Get(context.TODO(), req.NamespacedName, rs)
	if err != nil {
		return controllers.Result{}, err
	}

	// List the Pods matching the PodTemplate Labels
	pods := &corev1.PodList{}
	err = a.List(context.TODO(), client.InNamespace(req.Namespace).MatchingLabels(rs.Spec.Template.Labels), pods)
	if err != nil {
		return controllers.Result{}, err
	}

	// Update the ReplicaSet
	rs.Labels["pod-count"] = fmt.Sprintf("%v", len(pods.Items))
	err = a.Update(context.TODO(), rs)
	if err != nil {
		return controllers.Result{}, err
	}

	return controllers.Result{}, nil
}

Output:

Examples ¶

Package

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

View all

alias.go

Directories

?	: This menu
/	: Search site
f or F	: Jump to

Path	Synopsis
example
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
cache/informertest
client
client/apiutil
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
envtest/printer
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.
reconcile/reconciletest
recorder
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/scheme
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.
webhook/admission/types
webhook/types