Documentation
¶
Index ¶
Constants ¶
const ClaimFinalizerName = "opmodel.dev/dependents"
ClaimFinalizerName is the finalizer that holds a TransformerRegistration while instances still demand contracts it provides (0015:D3). It is distinct from the ModuleInstance cleanup finalizer: this one deletes nothing on release, it only decides when release is allowed.
const PlatformModulePath = "opmodel.dev/platforms/cluster@v0"
PlatformModulePath is the generated platform module's own identity: the reserved, never-published platforms namespace (0019:D6). Fixed rather than derived per generation so generated files are byte-stable across generations of the same spec, and distinct from every instance module path the render build could pair it with. Operator input to the library's generator, which owns everything else about the module including the core pin (its verified release, schema.DefaultSchemaVersion).
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CatalogAcquirer ¶
type CatalogAcquirer interface {
AcquireCatalogFromRegistry(ctx context.Context, modPath, version string) (*catalog.Catalog, error)
}
CatalogAcquirer acquires a published catalog by coordinate. The manager passes the shared library Kernel, whose AcquireCatalogFromRegistry both fetches and shape-gates: an artifact of another kind is refused by the library, not by a rule this repo maintains (0015:D10).
type ModuleInstanceReconciler ¶
type ModuleInstanceReconciler struct {
client.Client
// APIReader is an uncached reader (manager.GetAPIReader()) used for one-off
// reads that must not provision a cache informer.
APIReader client.Reader
Scheme *runtime.Scheme
RestConfig *rest.Config
ResourceManager *fluxssa.ResourceManager
EventRecorder events.EventRecorder
Renderer render.ModuleRenderer
// DefaultServiceAccount is the fallback SA name used when a
// ModuleInstance has an empty spec.serviceAccountName. Resolved in the
// instance's own namespace. Empty disables the default.
DefaultServiceAccount string
// Kernel is the shared, long-lived library Kernel constructed once at
// manager startup. It is the injection seam later enhancement-0001 slices
// consume to drive the render path; this slice wires it but does not read
// it on any reconcile path.
Kernel *kernel.Kernel
// MaxConcurrentRenders bounds how many ModuleInstances reconcile (and so
// render) at once: the manager's --max-concurrent-renders, applied as
// MaxConcurrentReconciles. Zero or negative keeps controller-runtime's
// default of one.
MaxConcurrentRenders int
// contains filtered or unexported fields
}
ModuleInstanceReconciler reconciles a ModuleInstance object. Dependencies are injected via struct fields at manager setup time.
func (*ModuleInstanceReconciler) Reconcile ¶
func (r *ModuleInstanceReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)
Reconcile runs the full ModuleInstance reconcile loop: CUE module synthesis and resolution from OCI registry, rendering, SSA apply, optional prune, and status commit.
func (*ModuleInstanceReconciler) SetupWithManager ¶
func (r *ModuleInstanceReconciler) SetupWithManager(mgr ctrl.Manager) error
SetupWithManager sets up the controller with the Manager.
Watches:
- ModuleInstance CRs (primary, generation-change predicate)
- Platform (cluster singleton) — every change re-enqueues all ModuleInstances via mapPlatformToModuleInstances so releases blocked on PlatformNotReady recover promptly when the platform is generated, and instances rendered under a superseded pin set or skew policy re-render. The generation predicate lives on For() (not as a global event filter) so it does not suppress the Platform watch, whose trigger (the reconciler's status update) does not bump generation.
MaxConcurrentRenders (the manager's --max-concurrent-renders) becomes the controller's MaxConcurrentReconciles: renders share nothing (library ADR-005, ADR-007), so the only bound is memory.
type ModulePackageReconciler ¶
type ModulePackageReconciler struct {
client.Client
// APIReader is an uncached reader (manager.GetAPIReader()) used for one-off
// reads that must not provision a cache informer.
APIReader client.Reader
Scheme *runtime.Scheme
RestConfig *rest.Config
ResourceManager *fluxssa.ResourceManager
EventRecorder events.EventRecorder
// Fetcher downloads Flux source artifacts. Injected for testability.
Fetcher opmsource.Fetcher
// Renderer loads and renders the CUE package from the extracted
// artifact directory. Injected for testability.
Renderer render.PackageRenderer
// DefaultServiceAccount is the fallback SA name used when a ModulePackage has
// an empty spec.serviceAccountName. Resolved in the ModulePackage's own
// namespace. Empty disables the default.
DefaultServiceAccount string
// Kernel is the shared, long-lived library Kernel constructed once at
// manager startup. It is the injection seam later enhancement-0001 slices
// consume to drive the render path; this slice wires it but does not read
// it on any reconcile path.
Kernel *kernel.Kernel
// MaxConcurrentRenders bounds how many ModulePackages reconcile (and so
// render) at once: the manager's --max-concurrent-renders, applied as
// MaxConcurrentReconciles. Zero or negative keeps controller-runtime's
// default of one.
MaxConcurrentRenders int
// contains filtered or unexported fields
}
ModulePackageReconciler reconciles a ModulePackage object.
func (*ModulePackageReconciler) Reconcile ¶
func (r *ModulePackageReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)
Reconcile runs the full ModulePackage reconcile loop: source resolution, artifact fetch, path navigation, CUE load, kind detection, render, apply, prune, and status commit.
func (*ModulePackageReconciler) SetupWithManager ¶
func (r *ModulePackageReconciler) SetupWithManager(mgr ctrl.Manager) error
SetupWithManager wires the controller into mgr. Watches:
- ModulePackage CRs (primary, generation-change predicate)
- OCIRepository, GitRepository, Bucket (artifact-change predicate, mapped to referencing ModulePackages) — only when those Flux source CRDs are installed; see fluxSourceCRDsInstalled.
- Platform (cluster singleton) — every change re-enqueues all ModulePackages via mapPlatformToModulePackages so packages blocked on PlatformNotReady recover promptly when the platform is generated. The generation predicate lives on For() (not as a global filter) so it does not suppress the Platform watch, whose trigger (the reconciler's status update) does not bump generation.
MaxConcurrentRenders (the manager's --max-concurrent-renders) becomes the controller's MaxConcurrentReconciles: renders share nothing (library ADR-005, ADR-007), so the only bound is memory.
type PlatformReconciler ¶ added in v0.7.0
type PlatformReconciler struct {
client.Client
Scheme *runtime.Scheme
EventRecorder events.EventRecorder
// Kernel is the shared, long-lived library Kernel constructed once at
// manager startup. The platform build runs on it.
Kernel *kernel.Kernel
// Store holds the current generated platform. Written here, read by the
// render path.
Store *platformstore.Store
// Registry is the CUE registry mapping (the manager's --registry value)
// the closure derivation resolves through; the build resolves through
// the mapping Kernel was constructed with. Empty falls back to the
// process CUE_REGISTRY.
Registry string
// Layout owns the module directories under the manager's --platform-dir.
Layout platformstore.Layout
// ModFiles serves published module files for the closure derivation.
// Nil constructs one from Registry on first use; a test may inject a
// fixture graph.
ModFiles platformmodule.ModFileSource
}
PlatformReconciler reconciles the singleton Platform CR into a platform CUE module on the operator's own disk (0019:D6). Per CR generation it derives the module's dependency closure from the pinned catalogs' published module files and generates the module through the library's platform-module helper (one importing #registry entry per subscription, the CR's version stamped as the expected-version tripwire, core pinned at the library's verified release), writes it under a per-generation directory, builds it through the kernel's shape-gated platform loader, reads the built platform's contract inventory as the gate on recording it (0015:D5, D18), and records the result together with the resolved skew policy (spec.skewPolicy, 0019:D7/D18) in the process-local store for the render path. The outcome surfaces on the CR's Ready condition: Generated, GenerateFailed, BuildFailed, OverSubscribedContracts or ComparablePredicates, with the non-gating ContractsFulfilled report beside it wherever a package was recorded.
func (*PlatformReconciler) Reconcile ¶ added in v0.7.0
Reconcile generates and builds the platform module for the cluster-singleton Platform and records the outcome on its status. It reconciles only the object named "cluster"; any other name is ignored without error. On delete it clears the store: workloads are frozen, never torn down, and the module directories are left for the next generation's prune or the next manager start.
func (*PlatformReconciler) SetupWithManager ¶ added in v0.7.0
func (r *PlatformReconciler) SetupWithManager(mgr ctrl.Manager) error
SetupWithManager wires the controller into mgr, watching both inputs of the tuple the generated package is a function of: the Platform singleton under a generation-change predicate, and every TransformerRegistration whose contribution to the active set changes, so a claim activating regenerates the platform without the CR being edited (0015:D13).
type TransformerRegistrationReconciler ¶
type TransformerRegistrationReconciler struct {
client.Client
Scheme *runtime.Scheme
EventRecorder events.EventRecorder
// Catalogs acquires the catalog a claim names. The manager passes the
// shared, long-lived library Kernel constructed once at startup.
Catalogs CatalogAcquirer
// Store holds the platform the Platform reconciler generated and built.
// Read-only here: acceptance judges against it and never writes it.
Store *platformstore.Store
}
TransformerRegistrationReconciler judges a provider module's claim that its catalog implements platform contracts (0015:D3). It decides one transition — whether a claim is accepted — and records the verdict on the claim's own status as conditions, accepted and observedGeneration.
The kind gets a reconciler of its own rather than a branch of the Platform reconciler: acceptance is per-claim and its verdict lives on the claim, so folding it in would make one claim's failure a platform-level failure, which is the misattribution acceptance exists to avoid.
It judges nothing until the platform exists. The built platform is read through the process-local store, never built here; a claim arriving before the Platform reconciler has generated one is requeued, because a verdict that depends on reconcile order is not a verdict.
An accepted claim activates when the ModuleInstance its providerRef names reports Ready=True (0015:D3), and activation latches: nothing here clears status.active, because the gate exists for install ordering — a provider's CRDs do not exist YET — and not for steady-state health. See gateActivation for what a live-tracking implementation would cost.
Activation is reported and inert: an active claim changes what the object reports, not what the cluster renders.
func (*TransformerRegistrationReconciler) Reconcile ¶
func (r *TransformerRegistrationReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)
Reconcile records a verdict on one claim, and guards its removal. A claim carrying a deletion timestamp goes to reconcileDeletion, which blocks while instances still demand contracts it provides (0015:D3) and releases the finalizer once they are gone.
func (*TransformerRegistrationReconciler) SetupWithManager ¶
func (r *TransformerRegistrationReconciler) SetupWithManager(mgr ctrl.Manager) error
SetupWithManager wires the controller into mgr. The generation predicate sits on For() rather than as a global filter so it does not suppress the two cross-object watches, whose triggers (the Platform reconciler's status update, a provider instance becoming Ready) do not bump a generation. The Platform watch is what lets a claim parked on PlatformNotReady recover as soon as the platform is generated; the ModuleInstance watch is what lets an accepted claim activate as soon as its provider is serving, instead of either waiting out the interval requeue.
Source Files