controller

type Backoff ¶

type Backoff struct {
	// Initial is the delay for attempt 0. Required.
	Initial time.Duration

	// Max is the upper bound on the returned delay. Required.
	Max time.Duration

	// Factor is the multiplicative factor between attempts. Values
	// <= 1 collapse the backoff to Initial.
	Factor float64
}

Backoff is a simple capped-exponential backoff helper. Reconcilers that track per-object retry counts (typically in CRD status) can use it to compute the next requeue delay without importing k8s.io/client-go/util/workqueue.

The zero value is NOT useful; callers should set Initial, Max, and Factor explicitly. A typical configuration:

b := controller.Backoff{
    Initial: 1 * time.Second,
    Max:     5 * time.Minute,
    Factor:  2.0,
}
delay := b.Next(ws.Status.RetryCount)

func (b Backoff) Next(attempt int) time.Duration

type ClusterClientManager ¶

type ClusterClientManager struct {
	// contains filtered or unexported fields
}

ClusterClientManager creates and caches controller-runtime clients for multiple Kubernetes clusters. Safe for concurrent use.

Lifted from control-plane-next/operators/workspace_controller/cluster_client_manager.go where it was the production implementation; the only change here is that ClusterConfig is now a parameter type the library owns rather than a project-level config struct.

func NewClusterClientManager(scheme *runtime.Scheme, logger *slog.Logger) *ClusterClientManager

func (m *ClusterClientManager) Get(cfg ClusterConfig) (client.Client, error)

func (m *ClusterClientManager) GetDefault() (client.Client, error)

func (m *ClusterClientManager) Refresh(clusterID string) error

type ClusterConfig ¶

type ClusterConfig struct {
	// ID is a stable identifier for the cluster. Used as the cache
	// key. Empty means default / in-cluster.
	ID string

	// KubeconfigPath, when non-empty, is loaded via clientcmd to
	// build the rest config. Empty means in-cluster.
	KubeconfigPath string

	// Context, when non-empty, overrides the current-context in the
	// loaded kubeconfig.
	Context string
}

ClusterConfig describes a remote Kubernetes cluster the operator can schedule workloads onto. The zero value (empty ID, empty KubeconfigPath) means "use the manager's in-cluster config" and is what GetDefaultClient passes.

type FinalizeFunc ¶

type FinalizeFunc[T client.Object] func(ctx context.Context, obj T) error

FinalizeFunc is the optional user-supplied callback invoked when the object is being deleted and Finalizer is set. It runs BEFORE the finalizer is removed; if it returns an error, the finalizer is left in place and controller-runtime requeues.

type ReconcileFunc ¶

type ReconcileFunc[T client.Object] func(ctx context.Context, obj T) (Result, error)

ReconcileFunc is the user-supplied domain-logic callback invoked by Reconciler[T].Reconcile after the object has been fetched and finalizer/deletion bookkeeping has been performed. Returning a non-nil error causes controller-runtime to requeue with backoff.

type Reconciler ¶

type Reconciler[T client.Object] struct {
	// Client is the controller-runtime client used to fetch and
	// patch the reconciled object. Populated by SetupWithManager.
	Client client.Client

	// Scheme is the runtime scheme used by the manager. Populated
	// by SetupWithManager.
	Scheme *runtime.Scheme

	// Recorder is an optional event recorder. When non-nil,
	// Reconciler emits a "Reconciling" / "Reconciled" event around
	// each reconcile attempt.
	Recorder record.EventRecorder

	// Log is the structured logger used by the base. Defaults to
	// slog.Default() when nil.
	Log *slog.Logger

	// Finalizer is the optional finalizer string. When non-empty,
	// Reconcile auto-adds the finalizer on first reconcile and
	// invokes FinalizeFunc on deletion before removing the
	// finalizer.
	Finalizer string
}

Reconciler is the generic base for typed controller-runtime reconcilers. Per-CRD shims embed it:

type WorkspaceController struct {
    controller.Reconciler[*v1alpha1.Workspace]
    DB        *sql.DB
    Publisher EventPublisher
}

func (r *WorkspaceController) ReconcileSpec(ctx context.Context, w *v1alpha1.Workspace) (controller.Result, error) {
    // user implements domain logic
    return controller.Done(), nil
}

func (r *WorkspaceController) FinalizeSpec(ctx context.Context, w *v1alpha1.Workspace) error {
    // user implements cleanup
    return nil
}

The Reconcile method on the embedded Reconciler is wired by calling SetupWithManager + a small Reconcile entry point (typically generated by `forge add crd`) that delegates to ReconcileFunc / FinalizeFunc.

The zero value is NOT ready to use: at minimum Client and Scheme must be populated by SetupWithManager.

func (r *Reconciler[T]) Run(
	ctx context.Context,
	req ctrl.Request,
	blank T,
	reconcile ReconcileFunc[T],
	finalize FinalizeFunc[T],
) (Result, error)

func (r *Reconciler[T]) SetupWithManager(
	mgr ctrl.Manager,
	concrete T,
	rec reconcile.Reconciler,
	opts SetupOptions,
) error

type Result ¶

type Result = ctrl.Result

Result is a thin alias of ctrl.Result. The library exports it so user code never has to import sigs.k8s.io/controller-runtime/pkg/reconcile directly — the helpers (Done, Requeue, Stop) are the canonical constructors and they all return Result.

func Done() Result

func Requeue(after time.Duration) Result

func Stop() Result

type SetupOptions ¶

type SetupOptions struct {
	// SkipDeletion, when true, filters Delete events out of the
	// watch. Use this when Finalizer is set and you want the
	// reconcile loop to handle cleanup via the deletion-timestamp
	// path rather than via Delete events.
	SkipDeletion bool

	// ExtraPredicates are AND-composed with any default predicate
	// the library applies. Empty means no extra filtering.
	ExtraPredicates []predicate.Predicate

	// Owns lists secondary resource types whose changes should
	// trigger a reconcile of the primary T. This is the standard
	// controller-runtime "Owns(&corev1.Pod{})" pattern.
	Owns []client.Object

	// Watches lets the operator declare cross-namespace or label-mapped
	// watches that don't fit the parent-owns-child controller-runtime
	// model (where owner references work). Each WatchSpec adds a
	// Watches(...) call to the controller builder with the supplied
	// EventHandler — typically handler.EnqueueRequestsFromMapFunc(...).
	//
	// Use this when secondary resources live in a different namespace
	// than the primary CR (owner references can't cross namespaces) or
	// when a label/annotation is the only link back to the parent.
	Watches []WatchSpec
}

SetupOptions configures how Reconciler[T] is wired into a manager.

type WatchSpec ¶

type WatchSpec struct {
	// Object is a typed empty value (e.g. &corev1.Pod{}) used for
	// scheme registration of the watched GVK.
	Object client.Object

	// Handler converts secondary-resource events into reconcile
	// requests for the primary type. Typically constructed via
	// handler.EnqueueRequestsFromMapFunc.
	Handler handler.EventHandler
}

WatchSpec describes a secondary-resource watch to register on the controller builder. The Object identifies the GVK to watch and the Handler determines how each event maps back to one or more reconcile.Requests on the primary type.