ImagePolicyWebhook — deprecated, the predecessor to Cosign

ImagePolicyWebhook was the built-in admission controller for image policy enforcement. It was deprecated in 1.22 and removed in 1.32. This lesson covers how it worked, why it was deprecated, the migration path to modern alternatives, and the lessons from its design.

How ImagePolicyWebhook worked

ImagePolicyWebhook was enabled with --enable-admission-plugins=ImagePolicyWebhook and configured with --image-policy-webhook-config-file. The configuration pointed at an external service that received an ImageReview for every Pod creation:

{
  "kind": "ImageReview",
  "apiVersion": "authentication.k8s.io/v1",
  "spec": {
    "containers": [
      {"image": "myapp:v1.0"},
      {"image": "library/redis:7"}
    ],
    "namespace": "prod"
  }
}

The service returned:

{
  "apiVersion": "authentication.k8s.io/v1",
  "kind": "ImageReview",
  "status": {
    "allowed": false,
    "reason": "image myapp:v1.0 is not from the approved registry"
  }
}

The API server applied the decision: allow or reject the Pod based on the service’s response.

sequenceDiagram
    participant AS as API server
    participant IPW as ImagePolicyWebhook service
    AS->>IPW: ImageReview (containers)
    IPW->>IPW: Evaluate policy
    IPW->>AS: ImageReview status (allowed, reason)
    AS->>AS: Apply decision

Why it was deprecated

Three reasons:

1. No signature support. ImagePolicyWebhook could check the registry, the image name, the tag — but it could not verify the image’s signature. The ImageReview carries the image string, not the digest. An attacker could push a malicious image with the same name and tag.
2. No SBOM support. ImagePolicyWebhook did not have a way to check the image’s SBOM (Software Bill of Materials) for vulnerabilities. The signature and SBOM use cases emerged after the controller was designed.
3. Configuration was cumbersome. The configuration required a kubeconfig-style file pointed at by --image-policy-webhook-config-file. The configuration was not first-class in the cluster.

The deprecation timeline:

A cluster upgraded past 1.32 has no ImagePolicyWebhook. The migration is required.

Migration to modern alternatives

Three paths:

1. Cosign + ValidatingAdmissionWebhook. Cosign signs images; a validating webhook verifies the signature against the cluster’s trust policy.

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: cosign-verifier
webhooks:
- name: verify.cosign.example.com
  clientConfig:
    service:
      name: cosign-verifier
      namespace: policy
      path: /verify
    caBundle: <base64 CA>
  rules:
  - operations: ["CREATE", "UPDATE"]
    apiGroups: [""]
    apiVersions: ["v1"]
    resources: ["pods"]
  admissionReviewVersions: ["v1"]
  sideEffects: None
  failurePolicy: Fail
  namespaceSelector:
    matchExpressions:
    - key: image-signature
      operator: In
      values: ["required"]

2. Kyverno. Kyverno has built-in image signature verification and a wider policy language.

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: verify-image-signatures
spec:
  validationFailureAction: Enforce
  rules:
  - name: verify-signatures
    match:
      resources:
        kinds: ["Pod"]
    verifyImages:
    - imageReferences:
      - "registry.example.com/*"
      attestors:
      - entries:
        - keys:
            publicKeys: |-
              -----BEGIN PUBLIC KEY-----
              ...
              -----END PUBLIC KEY-----

3. OPA/Gatekeeper. OPA evaluates Rego policies against the Pod’s image references.

package kubernetes.admission

deny[msg] {
  input.request.kind.kind == "Pod"
  container := input.request.object.spec.containers[_]
  not startswith(container.image, "registry.example.com/")
  msg := sprintf("image %v is not from the approved registry", [container.image])
}

Lessons from ImagePolicyWebhook

Three lessons:

1. Built-in admission controllers can become obsolete. A controller that ships with the API server can be deprecated when the use case evolves. The migration path must be planned in advance.
2. External lookups are a runtime dependency. A webhook that depends on an external service (registry, signature store) inherits that service’s reliability. The discipline is HA replicas and observability.
3. Declarative policy is more reliable. CEL-based policies are evaluated in the API server; webhook policies require an external service. The discipline is to prefer declarative where possible.

Production failure modes

1. ImagePolicyWebhook still enabled in 1.30.x. The cluster is past deprecation but the flag is still set. The fix is to remove the flag and migrate to a modern alternative.
2. No migration in progress. A 1.30 cluster with ImagePolicyWebhook and no migration plan will fail to upgrade past 1.32. The fix is to plan the migration before the next minor upgrade.
3. Migration to a less-capable alternative. A cluster that migrates to a webhook without signature verification loses the security improvement that motivated the original policy. The fix is to migrate to Cosign + Kyverno or Cosign + a custom webhook.

Cross-course references

• The Observability course covers the audit log entries for image policy decisions.
• The Linux course covers the OCI image format that Cosign signatures use.

Quiz

Production discipline

ImagePolicyWebhook is a lesson in admission control evolution. The controller’s deprecation timeline (1.22 deprecated, 1.32 removed) is the discipline: every built-in controller will eventually be replaced by a better alternative. The migration must be planned before the cutoff. The modern equivalent (Cosign + Kyverno, Cosign + a custom webhook) adds signature verification — a security improvement the old controller did not provide. A cluster that migrates to a modern alternative with signature verification has a supply chain policy that is auditable.