Documentation
¶
Overview ¶
Package reconcile contains high-level release reconciliation orchestration.
Index ¶
- Constants
- func ComputeBackoff(failureCount int64) time.Duration
- func ReconcileModuleInstance(ctx context.Context, params *ModuleInstanceParams, req ctrl.Request) (ctrl.Result, error)
- func ReconcileModulePackage(ctx context.Context, params *ModulePackageParams, req ctrl.Request) (ctrl.Result, error)
- type ClaimShrinkDecider
- type ModuleInstanceParams
- type ModulePackageParams
- type Outcome
- type WarningTracker
Constants ¶
const ( // BackoffBaseDelay is the initial retry delay after the first transient failure. BackoffBaseDelay = 5 * time.Second // BackoffMaxDelay is the maximum retry delay (cap for exponential growth). BackoffMaxDelay = 5 * time.Minute // StalledRecheckInterval is the periodic safety recheck for stalled failures, // guarding against misclassification. StalledRecheckInterval = 30 * time.Minute )
const DefaultModulePackageInterval = 5 * time.Minute
DefaultModulePackageInterval is the fallback requeue interval when spec.interval is not set.
const ( // FinalizerName is the finalizer registered on ModuleInstance resources // to ensure owned resources are cleaned up before deletion completes. FinalizerName = "opmodel.dev/cleanup" )
Variables ¶
This section is empty.
Functions ¶
func ComputeBackoff ¶
ComputeBackoff returns the exponential backoff delay for a given failure count. Formula: min(baseDelay * 2^(failures-1), maxDelay). Returns baseDelay when failureCount is 0 or 1.
func ReconcileModuleInstance ¶
func ReconcileModuleInstance( ctx context.Context, params *ModuleInstanceParams, req ctrl.Request, ) (ctrl.Result, error)
ReconcileModuleInstance orchestrates all phases of the reconcile loop. Phases run sequentially; errors halt progression. Status is always patched at the end via deferred function.
func ReconcileModulePackage ¶
func ReconcileModulePackage( ctx context.Context, params *ModulePackageParams, req ctrl.Request, ) (ctrl.Result, error)
ReconcileModulePackage runs the full ModulePackage reconcile loop: source resolution, artifact fetch, path navigation, CUE load, kind detection, render, apply, prune, and status commit. Mirrors the ModuleInstance loop but sources the CUE package from a Flux artifact instead of synthesizing it.
Types ¶
type ClaimShrinkDecider ¶
type ClaimShrinkDecider interface {
Decide(ctx context.Context, rendered *unstructured.Unstructured) (shrink.Decision, error)
}
ClaimShrinkDecider judges whether one rendered resource must be withheld from apply. The reconcile orchestrates the refusal; it does not implement the decision (Principle II).
type ModuleInstanceParams ¶
type ModuleInstanceParams struct {
Client client.Client
// APIReader is an uncached reader used for one-off reads (e.g. ServiceAccount
// existence checks for impersonation) that should not provision a cache informer.
APIReader client.Reader
RestConfig *rest.Config
ResourceManager *fluxssa.ResourceManager
EventRecorder events.EventRecorder
// Renderer produces the render result for a ModuleInstance. Must be non-nil;
// production wires render.KernelModuleRenderer, tests wire a stub.
Renderer render.ModuleRenderer
// DefaultServiceAccount is the fallback SA name used when a
// ModuleInstance has an empty spec.serviceAccountName. Empty disables
// the default and preserves the controller-client fallback.
DefaultServiceAccount string
// Warnings remembers each instance's last render warnings so RenderWarning
// events are emitted on transition only. Nil emits every non-empty set.
Warnings *WarningTracker
}
ModuleInstanceParams holds the dependencies injected into the reconcile loop.
type ModulePackageParams ¶
type ModulePackageParams struct {
Client client.Client
// APIReader is an uncached reader used for one-off reads (e.g. ServiceAccount
// existence checks for impersonation) that should not provision a cache informer.
APIReader client.Reader
RestConfig *rest.Config
ResourceManager *fluxssa.ResourceManager
EventRecorder events.EventRecorder
// Fetcher downloads Flux source artifacts. Typically
// &opmsource.ArtifactFetcher{} in production; tests inject a stub.
Fetcher opmsource.Fetcher
// Renderer loads and renders a CUE package from a local directory.
// Production wires render.KernelPackageRenderer; tests inject a stub. It is
// required — a nil Renderer is a programming error.
Renderer render.PackageRenderer
// DefaultServiceAccount is the fallback SA name used when a ModulePackage has
// an empty spec.serviceAccountName. Empty disables the default and
// preserves the controller-client fallback.
DefaultServiceAccount string
// Warnings remembers each package's last render warnings so RenderWarning
// events are emitted on transition only. Nil emits every non-empty set.
Warnings *WarningTracker
}
ModulePackageParams holds the dependencies for the ModulePackage reconcile loop.
type Outcome ¶
type Outcome int
Outcome classifies the result of a reconcile attempt. Drives requeue behavior and condition setting.
const ( // NoOp — all four digests match last applied. Ready=True, Reconciling=False. // Requeue: watch-driven, plus the controller's periodic interval where one // applies (ModulePackage requeues on spec.interval; ModuleInstance and // Platform are watch-only on the happy path today). NoOp Outcome = iota // Applied — resources applied successfully (no prune needed or prune disabled). // Ready=True, Reconciling=False. Requeue: same as NoOp (interval where the // controller defines one, otherwise watch-driven). Applied // AppliedAndPruned — resources applied and stale resources pruned. // Ready=True, Reconciling=False. Requeue: same as Applied. AppliedAndPruned // FailedTransient — temporary failure (network, API server). // Ready=False, Reconciling=True. Requeue: exponential backoff (ComputeBackoff). FailedTransient // FailedStalled — needs a spec or source change to resolve (invalid config, // invalid module). Ready=False, Stalled=True. Requeue: StalledRecheckInterval // (a long safety recheck guarding against misclassification), not none. FailedStalled )
func (Outcome) MetricLabel ¶
MetricLabel returns the snake_case label value for Prometheus metrics.
type WarningTracker ¶
type WarningTracker struct {
// contains filtered or unexported fields
}
WarningTracker remembers, per object, the set of advisory facts the last successful render reported, so the reconciler emits RenderWarning events only when an object's set changes rather than on every reconcile (0019:D18; spec events-emission). It is in-memory: a manager restart re-emits the current warnings once, which is the honest outcome (the events of the previous process are still on the object).
The set is keyed on the facts (advisoryFacts), not on the worded event text: rewording a warning presents an unchanged set as unchanged. Entries are keyed by namespaced name and dropped on deletion (Forget), so the map is bounded by the number of live objects. The zero value is ready to use; one tracker serves one kind.
func (*WarningTracker) Forget ¶
func (t *WarningTracker) Forget(key types.NamespacedName)
Forget drops the object's recorded set. Called on deletion.
func (*WarningTracker) Update ¶
func (t *WarningTracker) Update(key types.NamespacedName, facts []string) (changed bool)
Update records facts as the object's current advisory set and reports whether the set differs from the previously recorded one (order-insensitive, duplicates collapsed). A nil tracker reports every non-empty set as a change, so a caller wired without one still surfaces warnings.
Source Files