gem-hunter

This repository is a hard fork of kubernetes-sigs/cli-utils reducing it to the kstatus package and adding extensions for Flux's use cases.

We've forked cli-utils in 2023 as the upstream repo lagged months behind Kubernetes & Kustomize, which blocked our ability to use the latest Kustomize features in Flux. We have since made a number of improvements to the kstatus package specific to Flux's needs, and we intend to maintain this fork for the foreseeable future.

Besides Flux, the kstatus fork is also used by other projects such as Helm, Cilium, Pulumi, Talos and many others. The Flux maintainers are committed to maintaining it as a standalone library for the benefit of the wider Kubernetes ecosystem.

The kstatus package provides utilities for computing the status of Kubernetes resources, and for polling the cluster to determine when resources have reached a ready state or have stalled.

This package is used to determine the health and readiness of resources managed by Flux controllers, and to provide feedback to users about the state of their GitOps pipelines.

Instead of using kstatus directly, we recommend using the github.com/fluxcd/pkg/ssa package that offers a high level API for applying resources and waiting for them to be ready:

// WaitForSetWithContext checks if the given ObjMetadataSet has been fully reconciled.
// The provided context can be used to cancel the operation.
func (m *ResourceManager) WaitForSetWithContext(ctx context.Context, set object.ObjMetadataSet, opts WaitOptions) error

While the kstatus package can determine the status of native Kubernetes resources (e.g. a Deployment) and Flux custom resources that subscribe to the "abnormal-true" polarity pattern (Reconciling and Stalled conditions), it may not be able to determine the status of other custom resources in a reliable manner.

To overcome the limitations of kstatus, we have extended it with CEL expressions to enable Flux users to define the logic for computing the status which is evaluated against the resource's status fields. This allows accurate status computation for custom resources regardless of the conditions they use, and it also allows for more complex logic to be implemented in the status computation.

References:

• Flux Kustomization health expressions docs
• Flux HelmRelease health expressions docs
• CEL extensions for kstatus source code