runtime

package module
v0.49.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 13, 2024 License: Apache-2.0 Imports: 0 Imported by: 0

README

runtime

GoDoc

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:

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
features Feature gates configurations GoDoc
jiter Runtime jiter configuration applied to reconciliation interval 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
controller.WatchOptions Provides the capabilities to configure sharding of the reconciler resources 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.

Documentation

Overview

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

Directories

Path Synopsis
Package acl provides utilities for asserting cross-namespace access to GitOps Toolkit objects.
Package acl provides utilities for asserting cross-namespace access to GitOps Toolkit objects.
Package client provides runtime configuration options for a Kubernetes client, making it easier to consistently have the same configuration options and flags across GitOps Toolkit components.
Package client provides runtime configuration options for a Kubernetes client, making it easier to consistently have the same configuration options and flags across GitOps Toolkit components.
Package conditions provides utilities for manipulating the status conditions of Kubernetes resource objects that implement the Getter and/or Setter interfaces.
Package conditions provides utilities for manipulating the status conditions of Kubernetes resource objects that implement the Getter and/or Setter interfaces.
check
Package check provides warning and failure checks for the status of K8s object based on the various properties of the object status.
Package check provides warning and failure checks for the status of K8s object based on the various properties of the object status.
Package controller offers embeddable structs for use in your controller and underlying reconcilers, to help with conforming to GitOps Toolkit conventions.
Package controller offers embeddable structs for use in your controller and underlying reconcilers, to help with conforming to GitOps Toolkit conventions.
Package dependency contains an utility for sorting a set of Kubernetes resource objects that implement the Dependent interface.
Package dependency contains an utility for sorting a set of Kubernetes resource objects that implement the Dependent interface.
Package errors contains generic controller and reconciler runtime errors to be used by GitOps Toolkit components.
Package errors contains generic controller and reconciler runtime errors to be used by GitOps Toolkit components.
Package events provides a Recorder and additional helpers to record Kubernetes Events on an external HTTP endpoint.
Package events provides a Recorder and additional helpers to record Kubernetes Events on an external HTTP endpoint.
internal
Package leaderelection provides runtime configuration options for leader election, making it easier to consistently have the same configuration options and flags across GitOps Toolkit components.
Package leaderelection provides runtime configuration options for leader election, making it easier to consistently have the same configuration options and flags across GitOps Toolkit components.
Package logger provides runtime configuration options for logging, making it easier to consistently have the same configuration options and flags across GitOps Toolkit components.
Package logger provides runtime configuration options for logging, making it easier to consistently have the same configuration options and flags across GitOps Toolkit components.
Package metrics contains a Recorder and helpers for recoding standard metrics for all GitOps Toolkit components.
Package metrics contains a Recorder and helpers for recoding standard metrics for all GitOps Toolkit components.
Package object provides helpers for interacting with GitOps Toolkit objects using unstructured types.
Package object provides helpers for interacting with GitOps Toolkit objects using unstructured types.
Package patch implements patch utilities to help with proper patching of objects while reducing the number of potential conflicts.
Package patch implements patch utilities to help with proper patching of objects while reducing the number of potential conflicts.
Package pprof contains a helper to register pprof endpoints on a controller-runtime manager.
Package pprof contains a helper to register pprof endpoints on a controller-runtime manager.
Package predicates provides generic controller-runtime predicates for GitOps Toolkit components to filter events.
Package predicates provides generic controller-runtime predicates for GitOps Toolkit components to filter events.
Package probes contains a helper to configure sensible default health and ready probes on a controller-runtime manager.
Package probes contains a helper to configure sensible default health and ready probes on a controller-runtime manager.
Package reconcile provides helpers for the reconciliation.
Package reconcile provides helpers for the reconciliation.
Package testenv contains helpers to create and work with an encapsulated local Kubernetes test environment.
Package testenv contains helpers to create and work with an encapsulated local Kubernetes test environment.
Package tls contains helpers to convert Kubernetes secrets to TLS certificates.
Package tls contains helpers to convert Kubernetes secrets to TLS certificates.
Package transform contains utilities for transforming types.
Package transform contains utilities for transforming types.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL