reconciler

Overview ¶

pkg/reconciler/children.go

pkg/reconciler/conditions.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/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_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.konductor.io/last-commit

This annotation survives pod restarts, preventing spurious rebuilds.

pkg/reconciler/run_jobs.go

pkg/reconciler/run_mutation.go

pkg/reconciler/run_namespace_guard.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_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.konductor.io/generated-at: "2026-04-06T08:00:00Z"
orkestra.konductor.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_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.<kind>.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