Kubernetes ImagePolicyWebhook

Definition

ImagePolicyWebhook is a Kubernetes API-server admission plugin of type validating. For an in-scope Pod request, it constructs an imagepolicy.k8s.io/v1alpha1 ImageReview, sends that object to a configured backend, and accepts or rejects the request from the returned status.

It is distinct from a general validating admission webhook. ImagePolicyWebhook is enabled and configured in each API server rather than through a ValidatingWebhookConfiguration, and its backend receives only image strings, the namespace, and selected annotations—not the full Pod, requesting user, ServiceAccount, labels, security context, or owner information.

Current Status

As of this page's August 12, 2026 review, the Kubernetes v1.36 documentation still lists ImagePolicyWebhook, marks it disabled by default, and documents the same v1alpha1 wire API. Kubernetes warns that this alpha API has looser compatibility rules; the backend should check the request version, and the API server must enable imagepolicy.k8s.io/v1alpha1 through --runtime-config.

This older, specialized path now sits beside two different controls: ValidatingAdmissionPolicy, stable since Kubernetes v1.30 for declarative in-process CEL checks, and dynamic admission webhooks for fuller admission context or external decisions. Neither automatically turns ImagePolicyWebhook into a signature or provenance verifier; those checks must exist in its backend or in a separate supply-chain admission control.

A newly important boundary is Kubernetes image volumes, stable in v1.36. Kubernetes explicitly excludes images used as volume sources from ImagePolicyWebhook even though those OCI objects can carry artifacts such as model weights.

Decision Path

1. Configure every API server. Enable ImagePolicyWebhook, enable its alpha API group, and reference plugin configuration from --admission-control-config-file. The configuration sets kubeConfigFile, allowTTL, denyTTL, retryBackoff, and defaultAllow. The backend URL must use TLS; the kubeconfig can carry a CA and API-server client certificate and key.
2. Build a narrow review. In the Kubernetes v1.36 implementation, ordinary Pod requests contribute containers and initContainers; an ephemeralcontainers subresource request contributes the ephemeral container images. Each entry contains only its image reference. The request also carries the namespace and Pod annotations matching *.image-policy.k8s.io/*.
3. Use a cached decision or call the backend. The current implementation keys an in-memory response cache on the serialized ImageReview.spec. Allowed and denied responses use separate configured TTLs. On a miss, the API server POSTs the review to the backend and retries according to retryBackoff.
4. Apply one result to the set. The backend returns status.allowed for all reviewed images together, an optional denial reason, and optional auditAnnotations. It cannot return a Pod patch or replace a tag with a digest.
5. Handle backend failure. A connection or response failure rejects the request when defaultAllow is false. When it is true, the plugin admits the request and adds the audit annotation imagepolicywebhook.image-policy.k8s.io/failed-open=true.

Digest and Cache Boundary

Kubernetes accepts image names by tag or digest. A tag can later point to different content; a digest identifies fixed content. ImagePolicyWebhook sends the reference string that appears in the Pod, and its response has no mutation channel. Consequently, a backend may resolve and approve a tag while the stored Pod still contains that mutable tag. The tag can move before a kubelet pull, and an approval cached under that unchanged string can outlive the evidence used to approve it.

For high-assurance workloads, require the final stored image reference to be digest-pinned, and bind signature, provenance, inventory, and vulnerability evidence to that digest. If a separate component resolves or mutates tags, validate the resulting digest before admission completes. Set approval and denial TTLs against the freshness and revocation requirements of the evidence; a cache has no knowledge that a signing key was revoked, a vulnerability threshold changed, or a registry tag moved.

Keep the evidence categories separate. A signature can authenticate a statement about an artifact; provenance can describe how it was built; an AI bill of materials can inventory components; and a vulnerability assessment is time-dependent. None alone establishes that an AI workload is safe or appropriate.

Agent Context

Model servers, inference gateways, tool sandboxes, evaluators, training jobs, and controller sidecars are often delivered as container images. ImagePolicyWebhook can make admission conditional on an operator-defined evidence check before those components receive cluster compute, credentials, network reach, or production data.

The gate covers the execution images supplied in the relevant Pod request, not everything an AI workload may consume. OCI-backed model weights mounted through image volumes are excluded; models, plugins, or tools downloaded at runtime are not image references in the review; and data already present on persistent storage is outside its contract. Those paths need separate model-weight, network, storage, and runtime controls.

An allow result means only that the backend approved the supplied image set under its policy and available evidence. It says nothing about model behavior, factual reliability, autonomy, or fitness for a use case.

Governance and Safety

• Backend trust: the backend is a privileged policy decision point. Record its owner, code and policy version, trust roots, registry credentials, deployment isolation, availability design, and credential-rotation procedure. TLS protects the channel; it does not establish that the policy or evidence is correct.
• Limited identity context: the native review omits the requesting principal and ServiceAccount. Do not infer either from a user-supplied annotation. Use another admission control when policy needs authenticated caller identity or the full Pod object.
• Break-glass discipline: Kubernetes documents matching annotations as a possible exception channel but also says they are user-provided and not validated. Treat a ticket or override annotation as a claim to authenticate independently, constrain who may set it, require expiry, and audit its use.
• Availability choice: fail open preserves deployments during backend trouble but weakens enforcement precisely when evidence is unavailable. Fail closed preserves the gate but can block rollout and recovery. Choose deliberately by workload tier, then test backend outage, malformed responses, certificate failure, and recovery.
• Cache and revocation: a cached response can remain valid after backend policy or external evidence changes. Document TTL rationale, emergency cache-expiry strategy, and how already-running workloads are found and remediated after revocation.
• Audit evidence: backend auditAnnotations and the failed-open marker become durable evidence only when Kubernetes auditing is enabled and relevant events are retained. Backend logs alone cannot show a fresh call for every admission because the API server may serve a cached result.
• Information disclosure: the backend receives image repository names, namespaces, and selected annotation values. Classify that metadata, avoid secrets in annotations or denial reasons, and limit backend access and retention.
• Control-plane consistency: enablement, alpha API settings, configuration, CA material, cache TTLs, and failure policy must agree across API-server replicas. A mixed control plane produces request-path-dependent enforcement.

Operational Checklist

• State the exact admission objective: registry allowlist, digest-only references, signer identity, provenance predicate, vulnerability threshold, exception rule, or a documented combination.
• Test Pod create and update, init containers, the ephemeralcontainers subresource, multiple-image sets, denied images, backend failure, cached allow and deny, and excluded image volumes.
• Make the backend deny when it cannot authorize every image in the submitted set, and return short, non-sensitive denial reasons.
• Record the Kubernetes version, API-server flags, admission configuration digest, backend identity, policy digest, evidence source and timestamp, decision, and any exception identifier.
• Continuously inventory resolved runtime digests and reconcile them with admitted digests; admission is prospective and does not re-evaluate already-running Pods when policy or evidence changes.
• Layer the image gate with Pod Security Admission, least-privilege identity, network controls, artifact controls for image volumes and runtime downloads, and incident procedures. Image identity is only one deployment risk.

Limits and Failure Modes

• Mutable-reference race: approving a tag does not bind the decision to the bytes later pulled.
• Stale cached evidence: a cached allow can survive a policy update, key revocation, tag move, or newly disqualifying vulnerability until its TTL expires.
• Context blind spot: the backend cannot natively decide from user identity, ServiceAccount, full Pod fields, or related workload objects because they are absent from ImageReview.spec.
• Artifact blind spot: image volumes, runtime downloads, persistent-volume contents, and other non-container-image delivery paths are not reviewed.
• No continuous enforcement: changing the backend's policy does not evict or re-admit existing Pods.
• Fail-open exposure: defaultAllow: true turns backend failure into admission; without retained audit events, the exception may leave no useful governance record.

A historical implementation failure illustrates why every subresource path needs regression tests. CVE-2023-2727 allowed restricted images to enter through ephemeral containers in affected releases. Kubernetes fixed it in v1.24.15, v1.25.11, v1.26.6, and v1.27.3; current documentation and v1.36 source include ephemeral-container review. Operators should still run supported patch releases and test the path themselves.

Source Discipline

This entry uses the Kubernetes admission-controller reference for documented configuration, request scope, failure behavior, and annotation warnings; the generated Image Policy API reference for the wire schema; and Kubernetes v1.36.0 source for implementation-specific claims about request filtering, cache keys, audit-prefix behavior, and ephemeral-container handling. Tag and digest claims come from the Kubernetes images documentation, while image-volume status and scope are checked separately against current volume documentation.

Backend capabilities are described conditionally. ImagePolicyWebhook itself does not resolve registry tags, verify Sigstore or Notary Project signatures, evaluate SLSA provenance, read an SBOM, or scan vulnerabilities. A claim that a deployment enforces any of those properties needs the backend's policy, implementation, evidence format, trust configuration, and decision record.

Spiralist Reading

Spiralism reads ImagePolicyWebhook as a narrow checkpoint against anonymous software arrival. The image says, "run me." The control plane asks, "which reference, judged by which policy, with what recorded exception?" The answer is useful only when it stays attached to an immutable artifact and an auditable decision.

Related Pages

• Kubernetes Admission Webhooks
• Validating Admission Policy
• Kyverno
• OPA Gatekeeper
• Ratify
• Sigstore
• Notary Project
• SLSA Provenance
• OCI Artifacts
• AI Bill of Materials
• Kubernetes Image Volumes
• Kubernetes Ephemeral Containers
• Kubernetes Pod Security Admission
• Kubernetes Audit Logging
• Agentic Supply-Chain Vulnerabilities

Sources

• Kubernetes Documentation, Admission Controllers: ImagePolicyWebhook, reviewed August 12, 2026.
• Kubernetes Documentation, Image Policy API (v1alpha1), reviewed August 12, 2026.
• Kubernetes source, ImagePolicyWebhook implementation at v1.36.0, reviewed August 12, 2026.
• Kubernetes Documentation, Images, reviewed August 12, 2026.
• Kubernetes Documentation, Volumes: image, reviewed August 12, 2026.
• Kubernetes Documentation, Dynamic Admission Control, reviewed August 12, 2026.
• Kubernetes Documentation, Validating Admission Policy, reviewed August 12, 2026.
• Kubernetes Documentation, Auditing, reviewed August 12, 2026.
• Kubernetes Security Response Committee, CVE-2023-2727 security advisory, June 14, 2023; reviewed August 12, 2026.
• SLSA, Provenance v1.2, reviewed August 12, 2026.

Return to Wiki