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.
- 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.
- 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.
The packages build upon the following standards:
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
Several packages are available to align common runtime configuration flags across a set of controllers, easing the end-user operator experience.
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 likeconditions.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 withconditions.IsFalse
. - Compose
metav1.Condition
structs in a certain state using e.g.conditions.TrueCondition
orconditions.FalseCondition
. - Modify the conditions on a Kubernetes resource object using
conditions.Set
or one of the available scoped functions likeconditions.MarkTrue
. - Compose conditions based on other state and/or configurations using
conditions.SetAggregate
,conditions.SetMirror
andconditions.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
.
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.
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.
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.
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.
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 |
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.
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.
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.
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.