Validating Webhook

Intercept Deployment changes with advisory or enforcing validation

The operator includes an optional validating admission webhook that intercepts Deployment CREATE and UPDATE operations. It runs the same validation checks as the controller but at admission time, before the change is persisted.

How it works

The webhook resolves the matching ApplicationPersona through the same ordered fallback chain the controller uses: the app.kubernetes.io/name label on the Deployment, then the app label, then metadata.name, then spec.selector.matchLabels. If no persona matches, the deployment is allowed without validation.

An unlabelled Deployment is no longer exempt. Before operator 0.8.0 a Deployment without app.kubernetes.io/name on the object itself was skipped with “no app.kubernetes.io/name label; skipping persona validation”. Helm, kustomize, and most hand-written YAML label the pod template only, so in practice a large share of real workloads were never validated at all.

If you run webhook.mode: enforcing, workloads that previously passed unchecked may now be rejected. Nothing about those workloads changed; what changed is that Dorgu can finally see them. Review the personas they will now be validated against, or run one cycle in advisory mode and read the warnings first:

helm upgrade dorgu-operator oci://ghcr.io/dorgu-ai/dorgu-operator-charts/dorgu-operator \
  -n dorgu-system --reuse-values --set webhook.mode=advisory

Clusters with the webhook disabled, which is the default, are unaffected.

Modes

Advisory mode (default)

All deployments are allowed. Validation issues are returned as Kubernetes admission warnings, which appear in kubectl output:

Warning: [nginx] CPU limit 2 exceeds persona limit 500m
Warning: [nginx] no liveness probe; persona expects path /health
deployment.apps/nginx configured

Enforcing mode

Deployments with validation errors are denied. Warnings are still attached to allowed responses.

Error from server: admission webhook "validate-deployment.dorgu.io" denied the request:
Deployment violates ApplicationPersona 'nginx': replicas (0) below persona minimum (1);
persona requires runAsNonRoot but Deployment does not enforce it

Enforcing mode can block deployments and rollouts. Test thoroughly in advisory mode before switching to enforcing in production.

Validation checks

The webhook runs four validation functions:

Check	Returns
Resource limits	warnings
Replica counts	warnings + errors
Security context	errors
Health probes	warnings

The distinction matters in enforcing mode: errors cause denial, warnings are attached but do not block.

Check	Type	Condition
CPU limit exceeds persona	warning	Container CPU > persona CPU limit
Memory limit exceeds persona	warning	Container memory > persona memory limit
Below minimum replicas	error	Replicas < minReplicas
Above maximum replicas	warning	Replicas > maxReplicas
runAsNonRoot not enforced	error	Persona requires it, pod doesn’t set it
Privilege escalation allowed	error	Persona forbids it, container allows it
Missing liveness probe	warning	Persona specifies livenessPath, no probe configured
Missing readiness probe	warning	Persona specifies readinessPath, no probe configured

Enabling the webhook

Via Helm

webhook:
  enabled: true
  mode: advisory  # or "enforcing"

Via CLI flag

./bin/manager --enable-webhook --webhook-mode enforcing

TLS certificates

The webhook server requires TLS certificates. Options:

1. cert-manager (recommended) — The Helm chart supports cert-manager annotations for automatic certificate provisioning
2. Manual certificates — Provide certificates via flags:
   --webhook-cert-path /path/to/certs \
   --webhook-cert-name tls.crt \
   --webhook-cert-key tls.key
   
3. Self-signed — controller-runtime generates self-signed certificates automatically for development

Fail-open behavior

The webhook is designed to fail open:

• If the operator is down, Kubernetes skips the webhook (when configured with failurePolicy: Ignore)
• If the ApplicationPersona lookup fails (API error), the deployment is allowed with a log message
• If no persona matches the deployment on any rung of the discovery chain, the deployment is allowed without validation

This ensures the webhook never blocks deployments due to operator issues.

Controller validation

Continuous validation via the reconciliation loop

Configuration

All webhook configuration options