runtime

README

runtime

The fluxcd/pkg/runtime offers a set of standard controller runtime packages that can be used on their own, but are best (and at times, must be) used together to help with common operations.

Goals

• Provide a better development and review experience while working with a set of controllers by creating simple APIs for common controller and reconciliation operations, like working with Conditions and Events, and debugging.
• Provide utilities to make it easier to adhere to the Kubernetes API conventions and a selective set of other Kubernetes (SIG) standards like kstatus.
• Prefer adoption of existing standards and types (like metav1.Condition) over creating new ones.
• Provide solutions to common difficulties while performing certain Kubernetes operations as a controller, like patching.
• Standardise how a controller communicates with the outside world, to improve observation and operation experience.
• Standardise the way controller runtime settings are configured, to improve end-user experience.

Non-goals

• Become a toolbox for all problems, packages must be of interest to a wide range of controllers (and specifically, their runtime operations) before introduction should be considered.
• Adopting every relevant standard. Potential integrations will be carefully considered, and where they break backward compatibility, introduced only in major version releases.

Supported standards

The packages build upon the following standards:

• controller-runtime
• Kubernetes API conventions
• Kubernetes meta API conditions
• kstatus

Usage

To use the packages in your project, import github.com/fluxcd/pkg/runtime using go get or your dependency manager of choice:

go get github.com/fluxcd/pkg/runtime

Runtime configuration options

Several packages are available to align common runtime configuration flags across a set of controllers, easing the end-user operator experience.

Package	Description	Reference
client	Kubernetes runtime client configurations like QPS and burst
features	Feature gates configurations
jiter	Runtime jiter configuration applied to reconciliation interval
leaderelection	Kubernetes leader election configurations like the lease duration
logger	Runtime logger configurations like the encoding and log level

Working with Conditions

The conditions package can be used on resources that implement the conditions.Getter and/or conditions.Setter interface, to enhance the experience of working with Conditions on a Kubernetes resource object during reconcile operations.

More specifically, it allows you to:

• Get a Condition from a Kubernetes resource, or a specific value from a Condition, using conditions.Get or one of the other available getter functions like conditions.GetMessage.
• Check if a Kubernetes resource has a Condition of a given type using conditions.Has, or if it bears a Condition in a certain state, for example with conditions.IsFalse.
• Compose metav1.Condition structs in a certain state using e.g. conditions.TrueCondition or conditions.FalseCondition.
• Modify the conditions on a Kubernetes resource object using conditions.Set or one of the available scoped functions like conditions.MarkTrue.
• Compose conditions based on other state and/or configurations using conditions.SetAggregate, conditions.SetMirror and conditions.SetSummary.

For all available functions, see the package reference.

The package combines well with the genric meta API package types, and understands the kstatus Condition types if set up with conditions.WithNegativePolarityConditions.

Safe patching

The patch package offers a helper utility to safely patch a Kubernetes resource while taking into account a set of configuration options, and attempting to resolve merge conflicts and retry before bailing.

It can be configured to understand "owned" Condition types using patch.WithOwnedConditions, and offers other options like patch.WithObservedGeneration.

For all available functions and examples, see the package reference.

Forwarding Events

The events package contains an events.Recorder which can be used to forward events to an external endpoint that understands the events.Event payload. For GitOps Toolkit controllers, this is the notification-controller endpoint.

The package is best used in combination with the controller.Metrics helper, as this allows you to record and forward Kubernetes Events using the same API.

Recording Metrics

The metrics package offers a metrics.Recorder with a set of Prometheus collectors for common GitOps Toolkit Kubernetes resource objects metric points (gotk_*).

The package is best used in combination with the controller.Events helper, as this allows you to record metrics using controller-runtime types.

Controller helpers

The controller package offers a collection of helpers that can be embedded into a reconciler struct to provide them the capability to e.g. send Kubernetes Events and/or record metrics.

Helper	Description	Reference
controller.Events	Provides the capabilities to send Events to the Kubernetes API and an external event recorder
controller.Metrics	Provides the capabilities to record a set of common Prometheus metrics for a Kubernetes resource object
controller.WatchOptions	Provides the capabilities to configure sharding of the reconciler resources

Predicates

The predicates package offers a set of GitOps Toolkit common controller-runtime predicates, for example to notice annotation changes.

Predicate	Description	Reference
predicates.ReconcileRequestedPredicate	Filter meta.ReconcileRequestAnnotation changes from update events

Errors

The errors package contains a set of error types for generic reconciler errors. This provides consistent error messages for end-users and allows for e.g. error type checking.

Dependency ordering

The dependency package provides a topological sort function for Kubernetes resource objects that implement the dependency.Dependent interface. For example used in situations where you want to be able to schedule reconciliations as efficiently as possible, or in sequential batches in the right order.

NB: at present the dependency ordering only works for dependencies of the same type, this should be changed or expanded in a future iteration, partly because it would enable flux2#1599.

Debugging

The pprof package allows setting up additional Go pprof HTTP handlers on the metrics endpoint of a controller-runtime manager for debugging purposes. A list of exposed endpoints can be found in pprof.Endpoints.

See the package reference for further instructions on how to use the package.

Testing

The testenv package can be utilized to control the lifecycle of a local Kubernetes api-server used for testing purposes, it is built upon controller-runtime's envtest, and can be further configured using the same environment variables.

The package offers an additional set of helper utilities around envtest, allowing configuration of the runtime scheme and Custom Resource Definitions using testenv.WithScheme and testenv.WithCRDPath.

For all available functions, see the package reference.

Documentation

Overview

Package runtime and subpackages contain generic helpers for use with controller-runtime.