Skip to content

Files

Latest commit

8b7bf6e · Sep 6, 2022

History

History
This branch is 1 commit ahead of, 1008 commits behind fluxcd/pkg:main.

runtime

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
Jan 25, 2022
May 11, 2022
Sep 6, 2022
Apr 13, 2022
Jul 7, 2021
Jul 7, 2021
Sep 6, 2022
May 11, 2022
Oct 27, 2020
Jul 7, 2021
Jul 7, 2021
Jul 7, 2021
Aug 15, 2022
Jul 12, 2021
Jul 22, 2021
Jul 7, 2021
Oct 7, 2021
Sep 6, 2022
Jul 7, 2021
Aug 30, 2022
Jul 12, 2021
Sep 6, 2022
Sep 6, 2022

runtime

GoDoc

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:

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 GoDoc
leaderelection Kubernetes leader election configurations like the lease duration GoDoc
logger Runtime logger configurations like the encoding and log level GoDoc

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:

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 GoDoc
controller.Metrics Provides the capabilities to record a set of common Prometheus metrics for a Kubernetes resource object GoDoc

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 GoDoc

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.