Docs
Kubernetes
Security
Validating Webhooks

Validating Webhooks in Kubernetes

Validating Webhooks are admission controllers in Kubernetes that inspect API requests before they are persisted in the cluster. These webhooks allow administrators to enforce custom validation rules, ensuring that only compliant configurations are applied.

Unlike Validating Admission Policies, which are built into the Kubernetes API server, Validating Webhooks allow external services to dynamically evaluate and reject API requests based on business logic, compliance, or security requirements.

How Validating Webhooks Work

A ValidatingWebhookConfiguration registers an external HTTP service that receives API requests before they are stored. The webhook server evaluates the request and returns a response indicating whether the request should be allowed or denied.

Example: Basic Validating Webhook

The following webhook blocks Pods running as root:

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: restrict-root-pods
webhooks:
  - name: validate.pods.k8s.thalassa.cloud
    rules:
      - apiGroups: [""]
        apiVersions: ["v1"]
        resources: ["pods"]
        operations: ["CREATE", "UPDATE"]
    clientConfig:
      service:
        name: validation-service
        namespace: webhook-namespace
        path: "/validate"
      caBundle: <base64-encoded-ca-cert>
    admissionReviewVersions: ["v1"]
    failurePolicy: Fail
    sideEffects: None

Explanation

  • webhooks → Defines the webhook behavior.
  • rules → Specifies which resources and operations the webhook applies to.
  • clientConfig → Defines the external validation service endpoint.
  • failurePolicy → Determines whether to reject requests if the webhook is unreachable.
  • sideEffects → Declares whether the webhook modifies objects.

High Availability Considerations

Installing a Validating Webhook introduces a critical dependency on the availability of the webhook service. If the webhook service becomes unavailable, it can block all API modifications, preventing cluster operations.

Best Practices for High Availability

  • Deploy the webhook with multiple replicas using a highly available architecture.
  • Use PodDisruptionBudgets (PDBs) to prevent all webhook pods from being terminated at the same time.
  • Use a failure-tolerant failurePolicy (Ignore instead of Fail) if availability cannot be guaranteed.
  • Ensure webhook endpoints are properly load-balanced to avoid single points of failure.
  • Use readiness probes to prevent an unready webhook service from blocking API requests.

Prefer Admission Validation Policies Over Webhooks

Admission Validation Policies (based on Common Expression Language - CEL) are Kubernetes-native alternatives to webhooks for enforcing security policies. If your webhook solution cannot be configured for high availability, use Validating Admission Policies instead.

When to Choose Admission Validation Policies Over Webhooks:

  • When no external service dependency is desired.
  • When high availability cannot be ensured.
  • When enforcing security and compliance policies that can be expressed using CEL.

Summary

  • Validating Webhooks allow for custom validation logic before Kubernetes API requests are persisted.
  • Ensuring high availability is critical to prevent API disruptions.
  • Admission Validation Policies should be preferred over webhooks for security policies when HA cannot be guaranteed.

Additional Resources

Validating Admission Policies