reconciler

Overview ¶

pkg/reconciler/children.go

pkg/reconciler/children_gvr.go

pkg/reconciler/conditions.go

pkg/reconciler/cross_util.go

pkg/reconciler/generic.go

pkg/reconciler/generic_autoscale.go

AutoscaleTarget implementation for GenericReconciler.

GenericReconciler implements the three AutoscaleTarget methods so it can be passed directly to NewAutoscaler. The autoscaler calls these methods; user code should not call them directly.

ResizeWorkers — fully wired via ResizableSemaphore. SetQueueDepthLimit — enforced atomically in Workqueue.Enqueue. SetResyncInterval — drives an independent resync goroutine that re-enqueues

all cached objects at the declared interval. 0 = idle (informer handles
baseline resync). The goroutine is started once by startCRDWorkers via the
ResyncLoopStarter interface; SetResyncInterval adjusts its rate at runtime.

pkg/reconciler/generic_namespace.go

Namespace guard wiring for GenericReconciler.

RestrictedNamespaces and AllowedNamespaces live on orktypes.CRDEntry directly — not on OperatorBoxConfig. GenericReconciler stores the full CRDEntry as r.crd, so the guard reads r.crd.RestrictedNamespaces and r.crd.AllowedNamespaces directly.

namespaceGuardFunc is called once per runResourceGroup invocation and returns a closure. run_*.go files call it after resolving the target namespace and before condition evaluation.

Fast path: returns nil when CRD has no restrictions — all run_*.go guard with "if guard != nil" so nil means zero allocation, zero check.

pkg/reconciler/generic_registry.go

KatalogRegistry — the interface GenericReconciler needs from the Kordinator registry to perform zero-API-call cross-CRD observation.

Why a local interface instead of importing pkg/kordinator directly:

pkg/reconciler → pkg/kordinator would create an import cycle.
pkg/kordinator already imports pkg/reconciler (for domain.Reconciler).
A local interface breaks the cycle — Go's implicit interface satisfaction
means *kordinator.ResourceKatalog satisfies this automatically.

pkg/reconciler/kube_reader_adapter.go

KubeReader adapter — bridges kubeclient.Kubeclient to the orktypes.KubeReader interface used by provider libraries.

Providers receive KubeReader not *kubeclient.Kubeclient because:

• The interface is narrow: GetSecret and GetConfigMap only — no write access
• Providers must not write Kubernetes resources (Orkestra owns cluster state)
• A narrow interface is easier to mock in provider tests
• The kubeclient package is internal; providers should not depend on it

pkg/reconciler/normalize.go

applyNormalize — canonical spec transformation.

Called as the first step of reconcileImpl, before mutation and validation. Returns a deep copy of the CR with normalize.spec fields replaced by their rendered values. The informer cache object is never modified.

Pipeline position:

informer cache → DeepCopy → applyNormalize → mutation → validation → runTemplateReconcile

After applyNormalize, every downstream step sees the normalized spec. The raw CR in etcd is unchanged — normalize is purely an in-memory operation.

Example — CronJob accepting both string and map schedule:

normalize:
  spec:
    schedule: >
      {{ if eq (typeOf .spec.schedule) "map" }}
        {{ cronExpr .spec.schedule.minute .spec.schedule.hour .spec.schedule.dayOfMonth .spec.schedule.month .spec.schedule.dayOfWeek }}
      {{ else }}
        {{ .spec.schedule }}
      {{ end }}

After normalize, .spec.schedule is always a cron string. onReconcile templates use {{ .spec.schedule }} directly — no branching needed.

pkg/reconciler/ptr_hooks.go

── Design note: pointer type parameter and the ObjectHooks adapter ───────────

WHY PTR, NOT T ────────────── GenericReconciler uses the type parameter name PTR rather than the conventional T to make the pointer expectation visible at every call site. Kubernetes informers store and return pointer values: when you create an informer for Database objects, every item retrieved from its cache is a *Database. The reconciler type-asserts the raw interface{} value from the cache with raw.(PTR), which succeeds only when PTR is a pointer type.

Users therefore write:

domain.ReconcileHooks[*Database]{OnReconcile: myFunc}

not:

domain.ReconcileHooks[Database]{OnReconcile: myFunc}  // wrong

This matches the pattern used throughout the Kubernetes ecosystem: controller-runtime, kubebuilder, and all typed client-go code work with pointer receivers and pointer type arguments for the same reason.

THE MISMATCH PROBLEM ──────────────────── Go generics are invariant: ReconcileHooks[*Database] and ReconcileHooks[domain.Object] are unrelated types even though *Database implements domain.Object. A direct type assertion:

anyHooks.(domain.ReconcileHooks[PTR])

fails at runtime whenever the caller provides ReconcileHooks[*Database] but PTR is inferred as domain.Object — which is exactly what happens in the runtime registry path inside konstructor.go, where the concrete type is not known at compile time.

WHY NOT TWO TYPE PARAMETERS ─────────────────────────── The constraint PTR interface{ *S; domain.Object } (with a second parameter S any) enforces at compile time that PTR is a pointer to a concrete struct. However, it cannot be satisfied by domain.Object (an interface), so the runtime registry path in konstructor.go — which infers PTR = domain.Object — would fail to compile. Updating konstructor.go to supply concrete types would require the registry to carry a separate typed factory per CRD, a much larger change with no benefit for the dynamic template path where no hooks exist.

THE OBJECTHOOKS ADAPTER ─────────────────────── Instead of storing domain.ReconcileHooks[PTR] on the reconciler, we store domain.ObjectHooks — a plain struct whose function fields are parameterised on domain.Object. The adapter is built once in NewGenericReconciler via the domain.HookBinder interface:

binder, ok := anyHooks.(domain.HookBinder)
hooks = binder.BindToObjectHooks()

Every domain.ReconcileHooks[T] value satisfies HookBinder automatically through its BindToObjectHooks() method. That method wraps each hook in a closure that performs obj.(T) before delegating to the typed function:

oh.OnReconcile = func(ctx context.Context, obj domain.Object) error {
    return fn(ctx, obj.(T))   // T = *Database at runtime
}

The assertion is safe because:

• The informer is always constructed for a single concrete type.
• Every item returned from its cache IS that type, even when retrieved as domain.Object (or interface{}).
• GenericReconciler already asserts raw.(PTR) earlier in reconcileCore, so obj arriving at the hook is guaranteed to be of the right type.

END-TO-END CALL PATH FOR TYPED HOOKS ──────────────────────────────────────

1. User writes: func DatabaseHooks() domain.AnyReconcileHooks { return domain.ReconcileHooks[*Database]{OnReconcile: onReconcile} }

2. Generated registry registers DatabaseHooks in HookRegistry.

3. konstructor.go calls HookFactory() → gets ReconcileHooks[*Database].

4. NewGenericReconciler receives it as domain.AnyReconcileHooks. PTR is inferred as domain.Object (from func() domain.Object newObj).

5. anyHooks.(domain.HookBinder) succeeds because ReconcileHooks[*Database] has BindToObjectHooks() via the generic method.

6. BindToObjectHooks() builds ObjectHooks with closures: obj.(*Database).

7. At reconcile time, reconcileCore does raw.(*Database or domain.Object) — whichever PTR resolves to — producing a domain.Object value whose underlying type is *Database.

8. r.hooks.OnReconcile(ctx, obj) invokes the closure from step 6. obj.(*Database) succeeds. The user's typed function receives *Database. ✓

CUSTOM HOOK WRAPPERS ──────────────────── If you wrap ReconcileHooks[T] in your own struct (e.g. to add middleware), implement domain.HookBinder by forwarding to the inner hooks:

type LoggingHooks[T domain.Object] struct {
    Inner domain.ReconcileHooks[T]
}
func (h LoggingHooks[T]) isHooks() {}
func (h LoggingHooks[T]) BindToObjectHooks() domain.ObjectHooks {
    oh := h.Inner.BindToObjectHooks()
    inner := oh.OnReconcile
    oh.OnReconcile = func(ctx context.Context, obj domain.Object) error {
        log.Info("reconciling", "name", obj.GetName())
        return inner(ctx, obj)
    }
    return oh
}

pkg/reconciler/rollback.go

Rollback implementation for GenericReconciler.

Three responsibilities:

1. snapshotSpec — writes the current spec to the previous-spec annotation before any spec change is applied. Called when generation changes.

2. shouldRollback — reads the operatorbox health state and evaluates the rollback trigger. Returns true when rollback should activate.

3. runRollback — applies the onRollback resource group using the previous spec hydrated into the resolver as .previous.*.

The rollback phase state lives in status.phase. The reconciler checks it at the top of reconcileImpl and blocks normal reconciliation while active. The only exit from rollback is a spec generation change.

pkg/reconciler/run_configmaps.go

pkg/reconciler/run_cronjobs.go

pkg/reconciler/run_cross.go

Cross-CRD HTTP fallback — fetches a CR detail from another Orkestra instance.

The primary path (informer cache, zero API calls) lives in run_template_reconcile.go in ReadCrossFromDeclarations. That function calls fetchCrossViaHTTP when the informer is unavailable (cross-binary, cross-cluster).

The full informer-cache path requires threading the Kordinator registry into GenericReconciler. ReadCrossFromInformer is called instead of fetchCrossViaHTTP for same-binary CRDs.

pkg/reconciler/run_delete_ordered.go

Sequential deletion with completion gates.

When onDelete.ordered: true the reconciler deletes resources in stages rather than relying on garbage collection. Each stage is a HookTemplates block. After submitting all deletes in a stage the reconciler polls the API server until every resource is confirmed gone, then advances to the next stage.

Deletion order within a stage is undefined; order is enforced between stages.

pkg/reconciler/run_deployments.go

pkg/reconciler/run_docker.go

Docker build/push dispatch — runs before resource groups in runTemplateReconcile.

The Docker hook performs a minimal docker build and optional push of the declared image. Results are injected into the resolver context via resolver.WithDocker() so subsequent template expressions and when: conditions can reference them.

Call sequence in runTemplateReconcile:

1. resolver = NewResolver(ctx, obj)
2. resolver = resolver.WithCross(ReadCross(...)) ← cross-CRD first
3. resolver, err = runGit(ctx, ...) ← Git second
4. resolver, err = runExternal(ctx, ...) ← HTTP third
5. resolver, err = runDocker(ctx, ...) ← Docker fourth
6. runDeployments, runServices, ... etc.

Results in template context:

.docker.image           → built image reference
.docker.buildSucceeded  → "true" or "false"
.docker.error           → error message (if any)
.docker.called          → "true" if hook executed

When: conditions can gate on these:

when:
  - field: docker.buildSucceeded
    equals: "true"

pkg/reconciler/run_docker_helper.go

pkg/reconciler/run_external.go

External HTTP call dispatch — runs before resource groups in runTemplateReconcile.

Calls are executed sequentially in declaration order. Results are injected into the resolver context via resolver.WithExternal() so subsequent template expressions and when: conditions can reference them.

Call sequence in runTemplateReconcile:

1. resolver = NewResolver(ctx, obj)
2. resolver = resolver.WithCross(ReadCross(...)) ← cross-CRD first
3. resolver, err = runExternal(ctx, resolver, ...) ← HTTP calls second
4. runDeployments, runServices, ... etc. ← resources use results

Results in template context:

.external.<name>.status   → HTTP status code ("200", "404", "503")
.external.<name>.body     → response body (first 4096 bytes)
.external.<name>.error    → error message on failure
.external.<name>.called   → "true" if the call was made

When: conditions on deployments can gate on these:

when:
  - field: external.health-check.status
    equals: "200"

pkg/reconciler/run_foreach.go

forEach expansion — expands template sources with a forEach declaration into N resolved sources, one per element in the list field.

forEach works on every resource type. The expansion happens before the resource-specific run_*.go function is called — each run_*.go function receives an already-expanded slice and is unaware of forEach.

Expansion sequence in runTemplateReconcile:

deployments := expandForEachDeployments(resolver, t.Deployments)
runDeployments(ctx, kube, resolver, obj, deployments, update)

YAML:

onReconcile:
  deployments:
    - name: "{{ .metadata.name }}-{{ .item }}"
      image: "{{ .spec.image }}"
      forEach:
        field: spec.regions
        as: item

For CR with spec.regions: ["us-east-1", "eu-west-1"]: Produces two DeploymentTemplateSources:

{Name: "my-app-us-east-1", Image: "nginx:latest", ...}
{Name: "my-app-eu-west-1", Image: "nginx:latest", ...}

The expansion resolves ALL template expressions immediately — the returned slice contains static (non-template) values ready for the registry functions.

when: and anyOf: on forEach sources are evaluated per-item — each expanded source may pass or fail conditions independently.

pkg/reconciler/run_git.go

Git hook dispatch — runs before external calls and resource groups in runTemplateReconcile.

The Git hook performs a minimal clone/fetch of the declared repository, computes the current commit hash, detects whether the commit changed since the previous reconcile, and injects results into the resolver context via resolver.WithGit().

Call sequence in runTemplateReconcile:

1. resolver = NewResolver(ctx, obj)
2. resolver = resolver.WithCross(ReadCross(...)) ← cross-CRD first
3. resolver, err = runGit(ctx, gvk, resolver, ...) ← Git second
4. resolver, err = runExternal(ctx, ...) ← HTTP third
5. resolver, err = runDocker(ctx, ...) ← Docker fourth
6. runDeployments, runServices, ... etc.

Results in template context:

.git.commit     → HEAD commit hash
.git.changed    → "true" if commit changed since last reconcile
.git.path       → working directory path
.git.error      → error message if operation failed
.git.called     → "true" if Git hook executed
.git.succeeded  → "true" if Git operation succeeded

When: conditions can gate on these:

when:
  - field: git.changed
    equals: "true"

Change detection is annotation-based — the last-seen commit is stored in:

orkestra.orkspace.io/last-commit

This annotation survives pod restarts, preventing spurious rebuilds.

pkg/reconciler/run_hpas.go

pkg/reconciler/run_ingresses.go

pkg/reconciler/run_jobs.go

pkg/reconciler/run_mutation.go

pkg/reconciler/run_namespace_guard.go

pkg/reconciler/run_namespace.go

pkg/reconciler/run_pdbs.go

pkg/reconciler/run_providers.go

Provider dispatch — the engine that connects Katalog declarations to registered provider libraries.

This file is called from runTemplateReconcile after all Kubernetes resource groups (deployments, services, jobs, etc.) have been reconciled. It:

1. Skips immediately if no provider blocks are declared or no providers registered
2. Resolves template expressions in every declaration field
3. Evaluates when: conditions — drops declarations that do not pass
4. Calls provider.Reconcile(ctx, req) for each active block

On CR deletion (finalizer path), runProviderDelete is called instead. It calls provider.Delete for all declarations — no condition filtering.

Integration in runTemplateReconcile (after all Kubernetes resource groups):

if err := runProviders(ctx, obj, resolver, rc.ProviderBlocks, providerRegistry, kubeReader); err != nil {
    return fmt.Errorf("providers: %w", err)
}

Integration in the finalizer handler:

if err := runProviderDelete(ctx, obj, resolver, rc.ProviderBlocks, providerRegistry, kubeReader); err != nil {
    return fmt.Errorf("provider cleanup: %w", err)
}

pkg/reconciler/run_pvcs.go

pkg/reconciler/run_pvs.go

pkg/reconciler/run_replicasets.go

pkg/reconciler/run_secrets_tls.go

TLS certificate generation and secret rotation for Orkestra secrets.

Extends the once: true pattern with:

• rotateAfter: <duration> — time-based rotation using a generated-at annotation
• tls: {...} — self-signed CA + signed certificate generation

The generated Secret is annotated with:

orkestra.orkspace.io/generated-at: "2026-04-06T08:00:00Z"
orkestra.orkspace.io/rotate-after: "90d"

On each reconcile, secretNeedsRotation reads these annotations and returns true when the threshold is crossed. The caller deletes and recreates.

TLS generation produces a Secret of type kubernetes.io/tls with:

tls.crt — PEM-encoded signed certificate
tls.key — PEM-encoded private key (for the server)
ca.crt  — PEM-encoded self-signed CA certificate

The CA is unique per Secret — appropriate for self-signed operator webhooks. For shared CAs across multiple services, store the CA in a separate Secret and reference it (planned: ca.secretRef field).

pkg/reconciler/run_secrets.go

Adds to the previous version:

• orktypes.EvaluateWhen instead of evaluateConditions (fixes anyOf: being ignored)
• rotateAfter: <duration> support — time-based credential rotation
• tls: {...} support — self-signed CA + signed certificate generation

Execution order per secret declaration:

1. EvaluateWhen(when:, anyOf:) — skip if conditions fail
2. Once/rotation check a. once: true, rotateAfter set — check annotation, delete if expired b. once: true, no rotateAfter — skip if exists c. once: false — standard create/update
3. Resolve template expressions — randomAlphanumeric evaluated here
4. TLS generation (if tls: is set) — generate CA + cert, skip data resolution
5. Create/Update/CopyToNamespaces
6. Annotate with generated-at — only when rotateAfter is set

pkg/reconciler/run_secrets_once.go

once: true on secrets — idempotent random secret generation.

The Kubernetes reconcile loop is called on every resync. A secret with random data (password, API key) would change every 30 seconds without the once: guard. once: true makes the create step check for existence first — if the Secret already exists, skip template evaluation entirely.

This is the check-before-generate pattern used by cert-manager and every other tool that generates credentials idempotently.

YAML:

secrets:
  - name: "{{ .metadata.name }}-credentials"
    once: true
    data:
      password: "{{ randomAlphanumeric 32 }}"
      apiKey:   "{{ randomHex 16 }}"
      jwtSecret: "{{ randomBase64 32 }}"

Behaviour:

• First reconcile: Secret does not exist → evaluate templates → create
• Every subsequent reconcile: Secret exists → skip completely (no-op)
• CR deleted: Secret deleted via owner reference (garbage collection)

once: true is IGNORED when update=true (onReconcile with reconcile: true). A secret in onReconcile should use static or deterministic template values. Combining once: true with reconcile: true logs a warning and skips the once: guard — the caller opted into continuous reconciliation.

once: false (default): standard create/update behavior, unchanged.

pkg/reconciler/run_serviceaccounts.go

pkg/reconciler/run_services.go

pkg/reconciler/run_statefulsets.go

pkg/reconciler/run_status.go

Status management — three layers:

Layer 1 — Automatic Ready condition.

Written after every reconcile regardless of Katalog declarations.
reason: ReconcileSucceeded on success, ReconcileError on failure.
No Katalog declaration required. Requires subresources.status in the CRD.

Layer 2 — Declarative status fields.

Written from status.fields declarations in the Katalog.
Template expressions resolved against the live CR object map.
Optional when: conditions gate individual field writes — this is what
makes declarative state machines possible.
Written only on successful reconcile.

Layer 3 — Child resource propagation.

Children are read after runTemplateReconcile and injected into the
resolver context via WithChildren. The returned resolver is used for
all subsequent status resolution.
Status field expressions reference children as:
  {{ .children.deployment.status.readyReplicas }}
  {{ .children.cronjob.status.lastScheduleTime }}
Children are keyed by lowercase Kind — matches kubectl conventions.

pkg/reconciler/run_template_reconcile.go

Execution order (each step can reference all previous steps):

1. Recieve NewResolver → .spec.*, .status.*, .metadata.*
2. r.readCross → .cross.<crd>.status.* (informer cache, zero API calls)
3. runExternal → .external.<n>.status, .body (HTTP calls)
4. forEach expand → N sources from N-element list fields
5. onCreate groups → deployments, services, secrets, configmaps, ...
6. onReconcile groups
7. runProviders → aws:, mongodb:, ... (external infra)

pkg/reconciler/run_validation.go