ADR-040: Admission Webhooks for Resource Validation¶
Category: architecture Provenance: human
Decision¶
Implement Kubernetes admission webhooks to validate Custom Resource specifications before they are persisted to etcd. Use cert-manager for TLS certificate management instead of Kopf's auto-managed webhooks (see ADR-065 for details).
Rationale¶
Pydantic validation happens during reconciliation, which means: 1. Users see "resource created successfully" but it fails later 2. No immediate feedback on typos or invalid values 3. Poor user experience debugging failed resources
Admission webhooks solve this by validating at admission time: 1. kubectl create fails immediately with clear error message 2. Users get instant feedback on what's wrong 3. Invalid resources never enter etcd 4. Better GitOps experience (ArgoCD shows validation errors immediately)
Additionally, webhooks enable enforcement of: - Resource quotas (e.g., max realms per namespace) - Cross-resource constraints (e.g., one Keycloak instance per namespace) - Namespace-based authorization (before resource is created)
Using cert-manager for certificates (instead of Kopf auto-management): - Kopf's auto-management depends on insights.ready_resources which doesn't complete - cert-manager is a standard Kubernetes pattern - Allows manual control over ValidatingWebhookConfiguration - See ADR-065 for full technical rationale
Agent Instructions¶
When implementing resource validation, use both Pydantic models (for type safety in code) AND admission webhooks (for early validation at K8s API boundary). Webhooks should validate specs synchronously and return clear error messages. Use kopf.on.validate decorators with explicit 'id' parameter for webhook paths. Ensure cert-manager is available for TLS certificate generation. Include readiness probe that checks webhook server port.
Rejected Alternatives¶
Pydantic validation only¶
No immediate feedback to users. Resources appear created but fail during reconciliation. Poor UX for debugging.
Use Kopf auto-managed webhooks with self-signed certs¶
Kopf's auto-management depends on insights.ready_resources.wait() which never completes in our operator setup. See ADR-065 for details.
Disable webhooks, only use CRD OpenAPI schema validation¶
CRD validation is limited (no cross-resource checks, no quotas, no complex logic). Webhooks enable richer validation.
Manual certificate management without cert-manager¶
Requires custom rotation logic. cert-manager is a standard solution.