Documentation
¶
Overview ¶
Package controller is the one general reconcile engine (ADR-0015): a store-watch informer feeds a rate-limited, deduplicating workqueue that worker goroutines drain by calling each kind's registered Reconciler — with exponential-backoff retry, RequeueAfter, status write-back (the reconciler's), and clean shutdown. Every control-plane feature contributes only a Reconciler; the engine owns the watch/queue/retry/worker machinery. k8s-free (the workqueue is hand-written).
Index ¶
Constants ¶
const SupervisionPeriod = 10 * time.Second
SupervisionPeriod is the steady-state requeue of a reconciler that owns running instances (ADR-0142): while they should be running it returns Result{RequeueAfter: SupervisionPeriod}, so the next pass checks them and replaces one that died without a store write.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Controller ¶
type Controller struct {
// contains filtered or unexported fields
}
Controller is the reconcile engine.
func (*Controller) Enqueue ¶ added in v0.4.0
func (c *Controller) Enqueue(req Request)
Enqueue adds req to the workqueue without blocking, as a store event would (deduplicated, re-queued on Done if in process), for a change no watch event carries: an edge verdict that another source's Set moved (ADR-0176), a run the workflow engine's goroutine advanced (ADR-0146). Safe from any goroutine, before Run, and a no-op after shutdown.
func (*Controller) Register ¶
func (c *Controller) Register(gvk v1.GroupVersionKind, r Reconciler)
Register binds a Reconciler to a gvk. Call before Run.
func (*Controller) Run ¶
func (c *Controller) Run(ctx context.Context) error
Run opens a store Watch per registered or watched gvk (the informer), starts the workers, blocks until ctx is cancelled, then drains the watches and workers — no leak.
func (*Controller) Watches ¶ added in v0.2.1
func (c *Controller) Watches(gvk v1.GroupVersionKind, mapFn MapFunc)
Watches enqueues mapFn's Requests on every change of a gvk, besides the gvk's own Reconciler if one is registered. Call before Run.
type Deps ¶
type Deps struct {
Store store.Store
Logger *slog.Logger
Workers int // number of worker goroutines; <1 defaults to 1
// RetryBackoffMax caps the failed-reconcile and re-Watch retry (controller.retryBackoffMax, ADR-0163); 0 ⇒
// maxBackoff.
RetryBackoffMax time.Duration
}
Deps configures the engine (internal component, ADR-0002 §1).
type MapFunc ¶ added in v0.2.1
MapFunc maps a changed object to the Requests of the objects whose reconcile reads it, such as a kind whose status is derived from it. A watch event carries no prior state, so the mapping must also cover what the object may have referenced before the change.
type Reconciler ¶
Reconciler is the per-kind logic a feature contributes. It must be idempotent (the queue is at-least-once). A delete surfaces as fault.NotFound from the store.
type Request ¶
type Request struct {
GVK v1.GroupVersionKind
Namespace v1.NamespaceName
Name v1.ObjectName
}
Request identifies the object to reconcile; it is also the workqueue key (comparable).
Source Files