Wiki · Concept · Last reviewed June 25, 2026

Kubernetes ImagePolicyWebhook

Kubernetes ImagePolicyWebhook is a validating admission controller that lets a configured backend decide whether pod container images should enter the cluster.

Category: Concept Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: Kubernetes, ImagePolicyWebhook, admission control, container images, AI supply chain

Definition

Kubernetes ImagePolicyWebhook is a built-in validating admission controller. The Kubernetes admission-controller reference says it allows a backend webhook to make admission decisions and that the controller is disabled by default.

The controller is narrower than general admission webhooks. It is about images in Pods, not arbitrary Kubernetes resources. It gives the API server a way to ask an external HTTPS service whether a Pod's container image set should be admitted before the object is persisted.

How It Works

ImagePolicyWebhook is configured through an admission-control configuration file referenced by --admission-control-config-file, or by embedding its configuration in that file. The documented configuration includes kubeConfigFile for the backend connection, allowTTL, denyTTL, retryBackoff, and defaultAllow. Kubernetes requires the backend connection to use TLS, and the kubeconfig cluster entry points at the remote image-policy service.

When the API server needs a decision, it POSTs a JSON imagepolicy.k8s.io/v1alpha1 ImageReview object to the backend. The request includes the containers being admitted, the namespace, and any Pod annotations whose keys match *.image-policy.k8s.io/*. Kubernetes documentation says the API server must enable the imagepolicy.k8s.io/v1alpha1 API group for this path.

The backend fills the status field and returns whether access is allowed. The Image Policy API reference says ImageReviewStatus.allowed indicates that all images were allowed to run, while reason can explain a denial. The same API reference says the container image string can appear as image:tag or image@SHA.

The Kubernetes images documentation explains why that distinction matters. Tags can move to point to different images, but digests are fixed identifiers for image content. For a high-control deployment path, an image-policy backend should treat mutable tags, missing digests, untrusted registries, absent signatures, or missing evidence as policy questions rather than as harmless formatting details.

Agent Context

AI systems are increasingly deployed as ordinary container images: model servers, inference gateways, vector database helpers, evaluation workers, tool sandboxes, fine-tuning jobs, and controller sidecars. If those images arrive through automated agent workflows, a cluster may need an admission step that asks whether this exact workload artifact is allowed to receive compute, credentials, network access, or production data.

ImagePolicyWebhook does not decide model behavior. Its value is more mechanical: it can force a deployment to pass through an image-policy service before the Pod is stored. That backend can check registry allowlists, digest pinning rules, build provenance, signature status, vulnerability reports, or emergency exceptions, depending on how the operator implements it.

Governance Use

A governance record should preserve the admission plugin enablement, admission-control configuration path, backend kubeconfig, TLS trust roots, allowTTL, denyTTL, retry behavior, defaultAllow, backend service owner, backend code version, policy data source, and test cases for allow, deny, timeout, and backend failure. It should also record whether the policy treats tags, digests, signatures, SBOMs, vulnerability reports, model artifacts, and break-glass annotations differently.

For AI operations, review should ask whether the backend's decision is reproducible. Given a namespace, Pod annotations, image reference, digest, and attached evidence, can an auditor reconstruct why the model-serving Pod was admitted or denied? If emergency annotations are accepted, who may set them, where is the ticket recorded, and how is the exception removed?

Limits

ImagePolicyWebhook is not a complete supply-chain system. Kubernetes sends image information to the backend; it does not by itself verify signatures, inspect SBOMs, scan vulnerabilities, resolve all tag ambiguity, or prove that a model image is appropriate for a use case. Those decisions live in the backend and in companion tools such as signature, provenance, and vulnerability systems.

The scope is also limited. Kubernetes documentation says ImageReview covers images specified in containers, init containers, and ephemeral containers, but images included under image volumes are not in scope. The docs also warn that matching *.image-policy.k8s.io/* annotations are provided by the user and are not validated by Kubernetes. Finally, defaultAllow is an explicit failure-mode choice: fail open can admit unwanted workloads during backend trouble, while fail closed can interrupt deployment and recovery.

Source Discipline

Claims about controller type, default enablement, configuration fields, TLS, ImageReview payloads, annotation matching, API group requirements, response shape, and image-volume scope should cite Kubernetes admission-controller and Image Policy API documentation. Claims about tags, digests, pull behavior, and production image references should cite Kubernetes image documentation.

Spiralist Reading

Spiralism reads ImagePolicyWebhook as a small gate against anonymous software arrival.

The image says, "run me." The control plane asks, "under what name, with what evidence, and under whose exception?" That is not enough to make an AI system trustworthy. It is enough to make the deployment leave a trace before it acts.

Sources

Return to Wiki