controllerutils

package
v0.2.0-rc1 Latest Latest
Warning

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

 Go to latest Published: Oct 17, 2025 License: MIT Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	EventTypeNormal  = "Normal"
	EventTypeWarning = "Warning"
)

Event type constants

View Source 
const (
	ConditionTypeReady       = "Ready"
	ConditionTypeProgressing = "Progressing"
	ConditionTypeFailure     = "Failure"
	ConditionTypeDiscovered  = "Discovered"
	ConditionTypeCacheWarm   = "CacheWarm"
)

Standard condition types for AIM resources

View Source 
const (
	ReasonReconciling      = "Reconciling"
	ReasonAvailable        = "Available"
	ReasonFailed           = "Failed"
	ReasonDiscoveryRunning = "DiscoveryRunning"
	ReasonDiscoveryFailed  = "DiscoveryFailed"
	ReasonDiscovered       = "Discovered"
	ReasonJobPending       = "JobPending"
	ReasonJobFailed        = "JobFailed"
	ReasonJobSucceeded     = "JobSucceeded"
)

Standard condition reasons

Variables

This section is empty.

Functions

func AddFinalizer 

func AddFinalizer(obj client.Object, finalizer string)

AddFinalizer adds the specified finalizer to the object

func ApplyDesiredState 

func ApplyDesiredState(
	ctx context.Context,
	k8sClient client.Client,
	scheme *runtime.Scheme,
	desired []client.Object,
	config ApplyConfig,
) error

ApplyDesiredState applies the desired set of objects via Server-Side Apply (SSA). Objects are applied in deterministic order: by GVK, then namespace, then name.

func CleanAMDGPUName added in v0.1.6 

func CleanAMDGPUName(gpuID string) string

func CompareClusterQueues 

func CompareClusterQueues(a, b kueuev1beta1.ClusterQueue) bool

func ComparePriorityClasses 

func ComparePriorityClasses(a, b kueuev1beta1.WorkloadPriorityClass) bool

func CompareResourceFlavors 

func CompareResourceFlavors(a, b kueuev1beta1.ResourceFlavor) bool

func CompareTopologies added in v0.1.6 

func CompareTopologies(a, b kueuev1alpha1.Topology) bool

func ConvertKaiwoToKueueClusterQueue 

func ConvertKaiwoToKueueClusterQueue(kaiwoQueue kaiwo.ClusterQueue) kueuev1beta1.ClusterQueue

func ConvertKaiwoToKueueResourceFlavor 

func ConvertKaiwoToKueueResourceFlavor(kaiwoFlavor kaiwo.ResourceFlavorSpec) kueuev1beta1.ResourceFlavor

func ConvertKaiwoToKueueResourceFlavors 

func ConvertKaiwoToKueueResourceFlavors(kaiwoFlavors []kaiwo.ResourceFlavorSpec) []kueuev1beta1.ResourceFlavor

func ConvertKaiwoToKueueSpec added in v0.1.6 

func ConvertKaiwoToKueueSpec(in kaiwo.ClusterQueueSpec) kueuev1beta1.ClusterQueueSpec

ConvertKaiwoToKueueSpec converts from Kaiwo's simplified ClusterQueueSpec to the actual Kueue version

func ConvertKaiwoToKueueTopologies added in v0.1.6 

func ConvertKaiwoToKueueTopologies(kaiwoTopologies []kaiwo.Topology) []kueuev1alpha1.Topology

func ConvertKaiwoToKueueTopology added in v0.1.6 

func ConvertKaiwoToKueueTopology(kaiwoTopology kaiwo.Topology) kueuev1alpha1.Topology

func CreateClusterQueue 

func CreateClusterQueue(nodePoolResources map[string]kueuev1beta1.FlavorQuotas, name string, cohort string) kaiwo.ClusterQueue

func CreateDefaultResourceFlavors 

func CreateDefaultResourceFlavors(ctx context.Context, c client.Client) ([]kaiwo.ResourceFlavorSpec, map[string]kueuev1beta1.FlavorQuotas, error)

func CreateDefaultTopology added in v0.1.6 

func CreateDefaultTopology(ctx context.Context, c client.Client) ([]kaiwo.Topology, error)

func CreateLocalQueue 

func CreateLocalQueue(ctx context.Context, c client.Client, name string, namespace string) error

CreateLocalQueue creates a LocalQueue in the given namespace.

func EmitEvent 

func EmitEvent(recorder record.EventRecorder, obj client.Object, eventType, reason, message string)

EmitEvent emits a Kubernetes event if a recorder is available

func EmitNormalEvent 

func EmitNormalEvent(recorder record.EventRecorder, obj client.Object, reason, message string)

EmitNormalEvent emits a Normal type event

func EmitWarningEvent 

func EmitWarningEvent(recorder record.EventRecorder, obj client.Object, reason, message string)

EmitWarningEvent emits a Warning type event

func EnsureNamespaceKueueManaged 

func EnsureNamespaceKueueManaged(ctx context.Context, k8sClient client.Client, namespaceName string) error

func FindFlavor 

func FindFlavor(flavors []kueuev1beta1.ResourceFlavor, name string) (kueuev1beta1.ResourceFlavor, bool)

func FindTopology added in v0.1.6 

func FindTopology(topologies []kueuev1alpha1.Topology, name string) (kueuev1alpha1.Topology, bool)

func HasFinalizer 

func HasFinalizer(obj client.Object, finalizer string) bool

HasFinalizer checks if the object has the specified finalizer

func LabelNode 

func LabelNode(ctx context.Context, c client.Client, nodeName, key, value string) error

func NewCondition 

func NewCondition(
	conditionType string,
	status metav1.ConditionStatus,
	reason string,
	message string,
) metav1.Condition

NewCondition creates a new condition with the given parameters

func PatchStatus 

func PatchStatus[T ObjectWithStatus[S], S any](
	ctx context.Context,
	k8sClient client.Client,
	obj T,
	originalStatus S,
) error

PatchStatus patches the status subresource if it changed from originalStatus. Sets ObservedGeneration to match metadata.generation. Uses retry logic to handle conflicts when the object is modified between read and update.

This function uses generics to provide type-safe status access. The only reflection used is for setting ObservedGeneration, which is unavoidable without adding methods to every status type.

func Reconcile 

func Reconcile[T ObjectWithStatus[S], S any](ctx context.Context, spec ReconcileSpec[T, S]) (ctrl.Result, error)

Reconcile implements the observe → plan → apply → status pattern.

High-level flow: 1. Ensure/Remove Finalizer 2. If deleting → finalize → remove finalizer → patch status → exit 3. Observe (read-only) 4. Short-circuit on observation failure → project error status → return 5. Plan (pure function) 6. Apply (SSA with deterministic ordering) 7. Project Status (from observation + errors) 8. Patch Status once 9. Return with appropriate requeue policy

func ReconcileWithoutStatus 

func ReconcileWithoutStatus(ctx context.Context, spec ReconcileWithoutStatusSpec) (ctrl.Result, error)

ReconcileWithoutStatus implements the observe → plan → apply pattern for controllers that maintain derived resources but don't need status updates.

High-level flow: 1. Observe (read-only) 2. Short-circuit on observation failure 3. Plan (pure function) 4. Apply (SSA with deterministic ordering) 5. Return with appropriate requeue policy

func RemoveDuplicateResourceFlavors 

func RemoveDuplicateResourceFlavors(flavors []kaiwo.ResourceFlavorSpec) []kaiwo.ResourceFlavorSpec

func RemoveFinalizer 

func RemoveFinalizer(obj client.Object, finalizer string)

RemoveFinalizer removes the specified finalizer from the object

func TaintNode 

func TaintNode(ctx context.Context, client client.Client, nodeName string, taint corev1.Taint) error

Types

type ApplyConfig 

type ApplyConfig struct {
	// FieldOwner for SSA
	FieldOwner string

	// EnablePruning enables deletion of previously-owned objects not in desired set
	EnablePruning bool

	// InventoryLabels are labels used to track owned objects for pruning
	InventoryLabels map[string]string
}

ApplyConfig configures the SSA apply operation

type NodeResourceInfo 

type NodeResourceInfo struct {
	Name          string
	CPU           int
	Memory        int
	Labels        map[string]string
	Unschedulable bool
}

func GetNodeResources 

func GetNodeResources(ctx context.Context, c client.Client) []NodeResourceInfo

type ObjectWithStatus 

type ObjectWithStatus[S any] interface {
	client.Object
	GetStatus() *S
}

ObjectWithStatus is a generic constraint for objects that have a typed status accessor. This allows type-safe status access without reflection (except for ObservedGeneration).

type ReconcileErrors 

type ReconcileErrors struct {
	ObserveErr  error
	PlanErr     error
	ApplyErr    error
	FinalizeErr error
}

ReconcileErrors captures errors from different reconciliation phases

func (ReconcileErrors) HasError 

func (e ReconcileErrors) HasError() bool

HasError returns true if any error is set

type ReconcileResult 

type ReconcileResult struct {
	Result ctrl.Result
	Error  error
}

ReconcileResult encapsulates the result of a reconciliation

type ReconcileSpec 

type ReconcileSpec[T ObjectWithStatus[S], S any] struct {
	// Client is the Kubernetes client for API operations
	Client client.Client

	// Scheme is the runtime scheme for GVK resolution
	Scheme *runtime.Scheme

	// Object is the resource being reconciled (must be fetched and passed in)
	Object T

	// Recorder is the event recorder for emitting Kubernetes events (optional)
	Recorder record.EventRecorder

	// FinalizerName is the finalizer to add/remove (optional)
	FinalizerName string

	// FieldOwner is the field manager name for SSA (required)
	FieldOwner string

	// ObserveFn gathers current cluster state (read-only).
	// Returns typed observation data and any errors encountered.
	ObserveFn func(ctx context.Context) (observation any, err error)

	// PlanFn computes desired state from spec + observation (pure function).
	// Returns slice of objects to apply via SSA.
	PlanFn func(ctx context.Context, obs any) (desired []client.Object, err error)

	// ProjectFn computes status from observation + reconcile errors.
	// Modifies Object.Status directly. Framework patches if changed.
	ProjectFn func(ctx context.Context, obs any, errs ReconcileErrors) error

	// FinalizeFn performs external cleanup during deletion (optional).
	// Should only interact with external systems, not owned children.
	FinalizeFn func(ctx context.Context, obs any) error
}

ReconcileSpec defines the callback-based reconciliation specification. Controllers provide closures that capture their specific types and logic.

Type parameters:

  • T: The object type being reconciled (must implement ObjectWithStatus[S])
  • S: The status type of the object

type ReconcileWithoutStatusSpec 

type ReconcileWithoutStatusSpec struct {
	// Client is the Kubernetes client for API operations
	Client client.Client

	// Scheme is the runtime scheme for GVK resolution
	Scheme *runtime.Scheme

	// FieldOwner is the field manager name for SSA (required)
	FieldOwner string

	// ObserveFn gathers current cluster state (read-only).
	// Returns typed observation data and any errors encountered.
	ObserveFn func(ctx context.Context) (observation any, err error)

	// PlanFn computes desired state from observation (pure function).
	// Returns slice of objects to apply via SSA.
	PlanFn func(ctx context.Context, obs any) (desired []client.Object, err error)
}

ReconcileWithoutStatusSpec defines the reconciliation specification for controllers that don't need status updates (e.g., derived resource controllers).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.