DevOps Dictionary

Kubernetes ValidatingAdmissionWebhook is an admission control mechanism that accepts or rejects Kubernetes API requests before the API server stores the object in etcd. In practical terms, it lets platform and security teams enforce rules such as “pods must not run privileged,” “images must come from approved registries,” or “production namespaces require owner labels.”

What it does

A ValidatingAdmissionWebhook checks Kubernetes API requests after authentication, authorization, and mutation have already happened. It cannot change the object. It can only allow the request, deny it, return a warning, or attach audit information.

You can use it to validate requests for built-in resources such as Pods, Deployments, Services, and Ingresses, as well as custom resources from CRDs.

How it works

1. A user, controller, CI job, or GitOps tool sends a request to the Kubernetes API server.
2. The API server runs authentication and authorization.
3. Mutating admission controllers may modify the object first.
4. The API server sends an AdmissionReview request to the configured webhook endpoint over HTTPS.
5. The webhook evaluates the request and returns an allowed: true or allowed: false response.
6. If the request is allowed, Kubernetes can store the object. If denied, the API request fails with the webhook’s error message.

The webhook is configured using a cluster-scoped ValidatingWebhookConfiguration object. That configuration tells Kubernetes which operations, API groups, API versions, and resources should be sent to the webhook.

Common use cases

• Security policy enforcement: Block privileged containers, host networking, unsafe Linux capabilities, or containers running as root.
• Image governance: Require images to come from approved registries or block mutable tags such as latest.
• Label and annotation checks: Require labels such as team, cost-center, environment, or owner.
• Namespace protection: Prevent changes to critical namespaces such as kube-system, prod, or platform-owned namespaces.
• CRD validation: Enforce rules on custom resources used by operators and platform APIs.
• API migration control: Block deprecated API versions before or during cluster upgrades.

Key parts of a ValidatingWebhookConfiguration

• rules: Defines which API operations and resources trigger the webhook, such as CREATE on pods.
• clientConfig: Points the API server to the webhook service or external URL, including TLS configuration.
• failurePolicy: Controls what happens if the webhook is unavailable. Fail blocks the request. Ignore lets it continue.
• namespaceSelector: Limits matching to namespaces with specific labels.
• objectSelector: Limits matching to objects with specific labels.
• timeoutSeconds: Sets how long the API server waits for the webhook response.
• sideEffects: Declares whether the webhook has side effects. Admission webhooks should generally avoid external writes during validation.
• admissionReviewVersions: Lists supported AdmissionReview API versions, commonly v1.

Simple example

Assume your company requires every production Deployment to include an owner label. A ValidatingAdmissionWebhook can inspect every CREATE and UPDATE request for Deployments in namespaces labeled environment=prod.

If a developer applies this manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: payments-api
  labels:
    app: payments-api
spec:
  replicas: 3

The webhook can reject it with a clear message:

Deployment "payments-api" is missing required label "owner"

After the developer adds owner: payments-team, the request is allowed.

ValidatingAdmissionWebhook vs MutatingAdmissionWebhook

A ValidatingAdmissionWebhook makes a decision. It allows or rejects a request.

A MutatingAdmissionWebhook changes the object before it is stored. For example, it can inject a sidecar container, add default labels, or set missing fields.

In the admission flow, mutating webhooks run before validating webhooks. This matters because validation usually sees the final object after defaults and mutations have been applied.

ValidatingAdmissionWebhook vs ValidatingAdmissionPolicy

ValidatingAdmissionPolicy is a Kubernetes-native way to validate requests using Common Expression Language, or CEL. It does not require running a separate webhook server.

A ValidatingAdmissionWebhook is more flexible because it can call custom code and external systems. For example, it can check an internal service catalog or verify image metadata from a registry. That flexibility comes with more operational work, including deployment, TLS, availability, monitoring, and upgrades.

Benefits

• Central policy enforcement: You can enforce standards across teams without relying only on code review or documentation.
• Fast feedback: Developers get an API error before unsafe or invalid objects reach the cluster.
• Works with many workflows: The same rule applies whether resources are applied by kubectl, Helm, GitOps, CI/CD, or controllers.
• Supports custom logic: You can validate against business rules, platform contracts, or external systems.

Tradeoffs and limitations

• Webhook outages can block deployments: With failurePolicy: Fail, an unavailable webhook may stop matching API requests.
• Latency affects API writes: Slow webhook responses make Kubernetes API operations slower.
• TLS must be managed: The API server requires a trusted HTTPS endpoint for the webhook.
• Bad rules can break controllers: A strict policy can block system controllers, operators, or GitOps tools if selectors are too broad.
• It does not validate existing objects automatically: Admission webhooks handle new API requests. They do not scan old objects unless those objects are updated.

Operational guidance

• Run webhook backends with at least two replicas when enforcing critical policies.
• Use short timeouts, often 2 to 5 seconds, to avoid tying up API server requests.
• Use namespaceSelector and objectSelector to avoid matching system components unless needed.
• Start with audit, warning, or non-production enforcement before blocking production workloads.
• Monitor webhook latency, error rate, and rejection counts.
• Test policies during Kubernetes upgrades, especially when API versions change. A practical upgrade checklist can reduce surprises during Kubernetes upgrades for startups.

Where it fits in platform workflows

ValidatingAdmissionWebhooks are often part of a broader platform control plane. For example, if your teams manage manifests with Terraform, admission validation can enforce runtime cluster rules after Terraform submits resources to the API server. This complements workflows such as deploying Kubernetes resources using Terraform.

The same pattern applies when platform teams manage cloud infrastructure through Kubernetes APIs. If you use Crossplane to provision cloud resources, a ValidatingAdmissionWebhook can enforce rules on Crossplane custom resources before they create real infrastructure. This is useful in setups like deploying AWS resources using Crossplane on Kubernetes.

Tools that commonly use admission webhooks

• OPA Gatekeeper: Uses admission control to enforce policies written with Rego and ConstraintTemplates.
• Kyverno: Uses admission control for validation, mutation, image verification, and policy-based automation.
• cert-manager: Uses webhooks for validation and defaulting of certificate-related custom resources.
• Custom platform services: Internal teams can build their own webhook servers for company-specific rules.

Summary

Kubernetes ValidatingAdmissionWebhook is a powerful way to enforce cluster policy at API request time. It is best suited for rules that must be applied consistently across tools and teams, especially security, compliance, naming, labeling, and platform contract checks. Use it carefully, because webhook availability and latency directly affect Kubernetes API writes.