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/controller.go — continuous webhook configuration reconciliation.

The webhook controller runs in the background and ensures that Orkestra's admission surface (validation, mutation, deletion protection, namespace protection) exists exactly when the user has declared it — and disappears when they have 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 controller removes the corresponding webhook)

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 controller returns only fatal initialization errors. Reconciliation itself is continuous and non-blocking.

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/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.

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

Responsibility ¶

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

• TLS HTTPS server that handles /validate, /mutate, /convert, /deletion-protection, and /namespace-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.