webhook

Overview ¶

webhook/admission.go — /validate and /mutate HTTP handlers.

The Kubernetes API server POSTs an AdmissionReview to /validate for every CREATE and UPDATE on a resource covered by the ValidatingWebhookConfiguration, and to /mutate for every CREATE and UPDATE covered by the MutatingWebhookConfiguration.

Mutation fires before validation in the Kubernetes admission chain, so defaults are applied before validation sees the object.

webhook/admission_evaluation.go — validation and mutation rule evaluation.

webhook/admission_review.go — Kubernetes AdmissionReview types.

These mirror the Kubernetes admissionregistration.k8s.io/v1 types. Declared here to keep the webhook package self-contained without importing the full k8s.io/api module where it isn't needed.

The Kubernetes API server sends an AdmissionReview to /validate and /mutate. Orkestra reads the Request, evaluates rules from the Katalog, and writes the Response. The API server reads the Response and either stores the object (allowed) or rejects it (denied).

webhook/conversion.go — /convert HTTP handler for CRD version conversion.

The Kubernetes API server POSTs a ConversionReview to this endpoint when it needs to convert a CR from one version to another. Orkestra applies the conversion rules declared in the Katalog for the object's Kind.

webhook/conversion_logic.go — CRD version conversion logic.

webhook/deletion_protection.go — /deletion-protection webhook handler.

Registered only when security.deletionProtection.enabled: true in the Katalog. Intercepts DELETE operations on CRDs owned by this operator and Orkestra's own resources (deployment, service, ingress, webhook configurations).

failurePolicy: Fail — if Orkestra is unreachable, DELETE is blocked. To decommission: set deletionProtection.enabled: false, redeploy, then delete.

webhook/housekeeper.go — self-healing maintenance of Orkestra's admission surface.

The housekeeper runs in the background and ensures that the webhook configurations Orkestra owns exist exactly when the Katalog declares them — and disappear when they do not.

Declarative Webhook Lifecycle

security.admission.enabled: true
    → create/update the validating and mutating webhook configurations

security.deletionProtection.enabled: true
    → create/update the deletion-protection webhook

(inverse: when disabled, the housekeeper removes the corresponding webhook)

Event-Driven Reconciliation ¶

The housekeeper uses a Kubernetes Watch on ValidatingWebhookConfiguration and MutatingWebhookConfiguration objects as the fast path. A DELETED event triggers an immediate reconcile — the window during which a webhook is absent is bounded only by the API server round-trip, not by a poll interval. MODIFIED events are intentionally ignored: every reconcile Update fires one, and reacting to it would create a tight loop. Content drift is caught by the safety ticker instead.

A safety ticker (HOUSEKEEPER_SYNC_INTERVAL, default 30 s) runs in parallel as a backstop for drift that Watch silently misses: partial mutations, silent stream drops on some managed clusters, and token expiry.

A buffered trigger channel (capacity 1) coalesces bursts — any number of rapid DELETE/MODIFY events produce exactly one reconcile call.

Cleanup Semantics ¶

Webhook configurations are not removed on pod restart by default. Cleanup is opt-in via security.admission.cleanupOnShutdown and security.deletionProtection.cleanupOnShutdown. This avoids race conditions during rollout where a new leader sees an existing webhook while the old leader is still shutting down.

The housekeeper returns only fatal initialization errors. Reconciliation itself is continuous and non-blocking.

webhook/infrastructure.go

Housekeeper reconcilers for infrastructure security state.

Two resources are applied once at startup by cmd/internal.ensureSecurity but have no ongoing reconciler — a human can silently break security by removing them after startup:

1. Namespace labels — the deletion-protection webhook uses ObjectSelector to narrow to labeled resources. Removing the orkestra.io/deletion-protection label from the operator namespace means the webhook no longer intercepts deletion attempts against the namespace itself. The safety ticker catches this at the normal reconcile cadence.

2. CRD conversion caBundle — conversion webhooks require the caBundle in the CRD's spec.conversion.webhook.clientConfig.caBundle. If stripped, any CR at an old API version fails conversion immediately. This is watched with a dedicated goroutine so the restore happens within a single API round-trip, not at the next safety-ticker interval.

Kubernetes API server semantics guarantee no reconcile loop: if the patcher produces no change to the stored object (caBundle already correct), no MODIFIED event is emitted. So the event chain terminates after at most two reconciles.

webhook/namespace_protection.go — /namespace-protection webhook handler.

Registered only when security.namespaceProtection.enabled: true in the Katalog. Intercepts CREATE and UPDATE on CRDs that declare allowedNamespaces or restrictedNamespaces, and rejects operations in forbidden namespaces.

failurePolicy: Fail — if Orkestra is unreachable, the operation is blocked.

webhook/registration.go — webhook configuration registration and cleanup.

At startup, when admission webhooks or deletion/namespace protection are enabled, Orkestra creates or updates the corresponding ValidatingWebhookConfiguration and MutatingWebhookConfiguration objects that tell the API server to call Orkestra during admission.

All registration functions are idempotent — safe to call on restart or from the reconciliation controller. Existing configurations are updated to match the current Katalog state.

webhook/strict_mode_protection.go — /strict-mode-protection webhook handler.

Registered only when security.deletionProtection.strictMode: true in the Katalog. Intercepts UPDATE operations on resources that carry the deletion-protection label and denies any request that removes that label — treating label removal as a deletion attempt.

Design ¶

This handler is intentionally separate from /deletion-protection. Deletion protection guards DELETE operations. Strict mode guards label removal on UPDATE. Keeping them separate keeps each handler focused and independently controllable.

Enforcement ¶

The webhook ObjectSelector is set to the deletion-protection label selector, so the API server only calls this handler when either the old or new object carries the label. The handler then checks:

oldObject has label AND newObject does not → DENY (label removal blocked)
otherwise → ALLOW

Enforcement is stateless: every decision is made by comparing old and new labels in the admission request. No in-process register is required.

Unlock ¶

To remove the label from a protected resource, set strictMode: false in the Katalog, edit the Orkestra ConfigMap, and restart Orkestra. The new pods will not register the strict-mode webhook, so label removal becomes possible again. This mirrors how deletion protection itself is disabled — the trust boundary is the Katalog, not a separate escape hatch.

Package webhook implements Orkestra's admission and conversion webhook surface as a domain.Komponent that can be registered and managed alongside other runtime components.

Stats key design ¶

Per-CRD stats (admission, conversion, deletion-protection, namespace-protection) are keyed by "group/version/resource" — the canonical GVR string. This is the merge key used by the control center when combining the runtime and gateway /katalog responses.

Conversion stats require a secondary lookup map (gvkToGVRKey) because the conversion webhook handler receives objects identified by apiVersion+kind, not by their resource plural. Using the full GVK ("group/version/Kind") as the key — rather than just "Kind" — avoids a collision when two CRD entries share the same kind name but differ by version (e.g. cronjob-v1 and cronjob-v2 both have kind: CronJob). Keying by kind alone would cause the second entry in the initialization loop to overwrite the first, so all recorded conversions would land on whichever version happened to be iterated last.

Responsibility ¶

The webhook package owns everything required to operate Kubernetes admission and conversion webhooks:

• TLS HTTPS server that handles /validate, /mutate, /convert, /deletion-protection, /namespace-protection, and /strict-mode-protection
• Webhook configuration registration and reconciliation with the API server
• All HTTP handlers for admission review processing
• Periodic controller that keeps webhook configurations in sync with the Katalog

The health package (pkg/health) handles only HTTP health and readiness probes. This package handles only the HTTPS webhook surface.

TLS ¶

TLS certificates are provisioned by cmd/internal.ensureSecurity before Start() is called. The certificate file paths are read from konfig.Security().Webhooks after ensureSecurity writes them there. WebhookServer never generates its own certificates — that is the caller's responsibility.

Lifecycle ¶

WebhookServer implements domain.Komponent:

New(kubeClient, katalog, konfig)
  → Start(ctx)    — validate TLS, register endpoints, start HTTPS server,
                    register webhook configs, start controller
  → Shutdown(ctx) — stop HTTPS server, clean up webhook configs on shutdown

All registration and reconciliation errors are logged and non-fatal. The HTTPS server starts only when at least one webhook capability is declared in the Katalog. When no capabilities are declared, Start() is a no-op.