Restrict Image Registries: The First Admission Policy You Should Ship (in Audit Mode)
Before digest pinning, before signature verification, before CVE gates: control which registries your cluster may pull from. And ship it for a fortnight in audit mode before you dare enforce it.
There is a natural instinct, once you install Kyverno, to reach for the impressive policies: verify signatures, block vulnerabilities, require digests. Resist it. The highest-value, lowest-drama policy is the boring one: images may only come from registries you control.
Why this one first
Every other image policy presupposes it:
- Digest pinning is meaningless if anyone can pull an unscanned image from anywhere.
- Signature verification is meaningless if unsigned images from public registries are pullable anyway.
- CVE gates are meaningless if the vulnerable image never transits a registry you scan.
A registry allow-list turns "every running image has been through scan-on-push" from an aspiration into an invariant. It is also the policy least likely to break workloads, because it fails structurally — the wrong registry is obvious at a glance — rather than subtly (a threshold, a timestamp, a key rotation).
The policy
One invariant: every running image has been through scan-on-push.
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
name: restrict-image-registries
spec:
background: true
rules:
- name: validate-registries
match:
any:
- resources:
kinds: [Pod]
exclude:
any:
- resources:
namespaces:
- kube-system
- flux-system
- kyverno
# ... platform namespaces
validate:
failureAction: Audit
allowExistingViolations: true
message: >-
Image comes from an unapproved registry.
pattern:
spec:
=(ephemeralContainers):
- image: "harbor.example.com/* | registry.gitlab.example.com/*"
=(initContainers):
- image: "harbor.example.com/* | registry.gitlab.example.com/*"
containers:
- image: "harbor.example.com/* | registry.gitlab.example.com/*"Details that matter:
- Exclude ephemeral and init containers too, or the bypass is one
kubectl debugaway. - Exclude platform namespaces explicitly — kube-system, flux-system, kyverno itself — or a chart upgrade fails in a way that is painful to diagnose.
allowExistingViolations: trueduring rollout, so existing workloads are reported but not flapped.
Audit first. Always.
Test the policy before it goes anywhere near the cluster:
kyverno apply policy.yaml --resource test-pod.yaml # enforce semantics
kyverno apply policy.yaml --resource test-pod.yaml --audit-warn # report semanticsThen ship it with failureAction: Audit and watch the violations for a fortnight. In our case the audit phase surfaced something no test fixture would have: a Kyverno mutating policy that rewrites every Docker Hub image to pull through our Harbor proxy cache — docker.io/nginx becomes harbor/dockerhub/library/nginx. A validating policy that forbids docker.io/* must account for that rewrite, or it will flag exactly the images that are already being routed correctly. Digest-based matching is immune to this; string-prefix matching is not.
Enforce only after the fortnight of audit shows a violation list you can read out loud and explain, item by item.
The honest scope statement
Kyverno blocks workloads at the point the Kubernetes API accepts them. It protects this cluster and nothing else. Anything running outside Kubernetes — a VM, an Azure App Service, a CI job's docker run — gets no protection from it.
That is fine, as long as you say it out loud. The portable gates are:
- Trivy exit codes in CI —
--exit-code 1 --ignore-unfixed --severity CRITICALruns anywhere, in 203 ms on a small image. - Registry-side blocking — Harbor's "prevent vulnerable images from running" (test it before trusting it; we have not yet).
Admission control is the last line, not the only one. It catches what leaks past CI and the registry, for the workloads that live where the policy does.
Series: Building a Container Image Security Stack. Next: the Kyverno policy that reads Trivy Operator CRDs at admission time — what works, and the three architectural limits that keep it from being a first-deployment gate.