Documentation
¶
Overview ¶
Package workload provides generic utilities for reconciling controller-owned workloads.
This package contains a generic Ensure function that handles the common pattern of fetching, creating, and patching Kubernetes workloads (Deployments, Jobs, StatefulSets, etc.) with consistent owner reference and drift detection.
Ensuring Workloads ¶
The Ensure function provides a generic reconcile pattern for any client.Object:
deployment, err := workload.Ensure(ctx, workload.EnsureOptions[*appsv1.Deployment]{
Client: client,
Scheme: scheme,
Owner: impulse,
NamespacedName: types.NamespacedName{Name: "my-dep", Namespace: ns},
Logger: log,
WorkloadType: "Deployment",
NewEmpty: func() *appsv1.Deployment { return &appsv1.Deployment{} },
BuildDesired: func() (*appsv1.Deployment, error) { return buildDeployment() },
NeedsUpdate: deploymentNeedsUpdate,
ApplyUpdate: applyDeploymentUpdate,
})
Behavior:
- Creates the workload if not found, setting controller owner reference.
- Patches existing workloads when NeedsUpdate returns true.
- Logs creation/update operations when logger is provided.
- Validates all required options before proceeding.
Options ¶
The EnsureOptions struct provides all knobs for reconciliation:
- Client, Scheme, Owner: Required controller-runtime dependencies
- NamespacedName: Identifies the workload to reconcile
- WorkloadType: Label for log messages (e.g., "Deployment")
- NewEmpty: Factory for zero-value target object
- BuildDesired: Constructs the desired workload state
- NeedsUpdate: Determines if patching is needed
- ApplyUpdate: Mutates current to match desired before patching
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Ensure ¶
Ensure fetches the workload identified by opts.NamespacedName, creating it if missing or patching controlled fields when drift is detected.
func PodTemplateChanged ¶
func PodTemplateChanged(current, desired *corev1.PodTemplateSpec) bool
PodTemplateChanged reports whether two PodTemplateSpec objects differ in the fields controllers commonly watch for drift (containers, init containers, volumes, labels, annotations, service account name, and image pull secrets). Callers can reuse this helper when deciding whether Deployments or StatefulSets need patching.
Types ¶
type EnsureOptions ¶
type EnsureOptions[T client.Object] struct { // Client is the controller-runtime client used for Get/Create/Patch operations. Client client.Client // Scheme is used when setting the controller reference on newly created workloads. Scheme *runtime.Scheme // Owner becomes the controller reference for the workload when it is created. Owner client.Object // NamespacedName identifies the workload to fetch or create. NamespacedName types.NamespacedName // Logger receives creation/update messages; optional but recommended. Logger logr.Logger // WorkloadType appears in log/error messages to aid debugging (e.g., "Deployment"). WorkloadType string // NewEmpty returns a zero-value object used as the Get target. NewEmpty func() T // BuildDesired returns the desired workload state for comparison/creation. BuildDesired func() (T, error) // NeedsUpdate determines whether the live object should be patched. NeedsUpdate func(current, desired T) bool // ApplyUpdate mutates the live object so it matches the desired state prior to patching. ApplyUpdate func(current, desired T) }
EnsureOptions provides the knobs required to reconcile a controller-owned workload.
Source Files