Skip to main content
You can pull configuration and metadata from ConfigMaps, external APIs, and—most powerfully—directly from an OCI image registry. This lesson shows how to use Kyverno’s image registry context to inspect container image configuration (for example, the default user) and make admission decisions based on that data. Alex has become experienced at writing Kyverno policies that validate Kubernetes resources: labels, annotations, security context, and more. He blocked Pods from running as root by checking the Pod spec. Then a developer applies a Pod manifest that looks fine—the Pod spec doesn’t request root—but it uses the ubuntu:latest image. Alex knows many base images (including Ubuntu) don’t set a USER in the Dockerfile, so by default they run as root.
The image outlines a challenge involving deploying a Pod with the "ubuntu:latest" image, pointing out that while the Pod manifest doesn't specify a user, the image runs as root by default. There is also a graphic of puzzle pieces with a question mark.
Alex’s policies had a blind spot: they validate only the Kubernetes manifest and can’t inspect the image contents stored in the registry. He needs a way to query the registry, fetch the image config (including the default User), and use that information inside a policy.
The image titled "Alex's New Challenge" shows a person named Alex facing a dilemma about writing a policy to analyze a container image's actual configuration beyond Kubernetes YAML.
This is exactly what Kyverno’s image registry context solves. The imageRegistry context lets Kyverno query an OCI registry for an image manifest and config, and then expose that data as a variable inside a policy. Provide a reference to the target image and Kyverno returns a structured JSON object with useful fields.
The image introduces the imageRegistry context, explaining that it allows Kyverno to fetch image metadata from an OCI registry and store it in a variable.
Example context entry:
  • imageData is the variable name you can reference in rules.
  • reference is the fully-qualified image (name:tag or name@digest) Kyverno will inspect.
When the policy runs, Kyverno queries the registry (internally similar to using the crane tool), fetches the manifest and the image config, and fills imageData with a structured JSON object. What does imageData contain? Typical keys include the resolved image, registry, repository, and two important structures: manifest and configData. Example shape:
The image contains a title, "What's Inside the imageData Variable?" and a description stating it is a rich JSON object containing the image's manifest and config.
The configData payload includes the image configuration returned by the registry, such as Entrypoint, Env, and User. On the CLI, you can inspect the same info using crane config:
The critical field for preventing root containers is the User value inside the image config (config.User). If an image author sets USER in the Dockerfile, User will contain that value. If USER is not set (common for many base images like Ubuntu), User will be empty or absent, meaning the container runs as root by default. How to deny Pods that use images configured to run as root Below is a Kyverno validate rule that checks each container in a Pod using foreach. For each container, it calls imageRegistry to fetch the image config and denies the Pod if the image User is empty.
Why this works:
  • match selects Pods for validation.
  • foreach walks each container in request.object.spec.containers (Pod may have multiple).
  • For each container, imageRegistry resolves the container image ({{ element.image }}) and stores the result in imageData.
  • The deny condition checks imageData.configData.config.User; if it is empty, the rule denies the Pod because the image will run as root by default.
Practical examples
  • Pod using Ubuntu (expected to be denied)
Applying it:
  • Pod using a non-root image (Kyverno image; expected to be allowed)
Applying it:
This enforces image-level best practices (the image author set a non-root USER) in addition to validating the Kubernetes manifest.
Kyverno must be able to reach the registry to fetch image metadata. For private registries, configure the appropriate image pull credentials in Kyverno so it can authenticate when requesting image data.
Advanced usage: transform registry JSON with JMESPath You can supply a jmesPath expression in the imageRegistry context to extract or compute exactly the value you need from the registry JSON. For example, compute the total image size (sum of layer sizes) and store it as a string:
This jmesPath expression:
  • selects manifest.layers[*].size,
  • sums them via sum(...),
  • converts the number to a string with to_string(...), and
  • stores the result in imageSize for use elsewhere (for example, to deny images larger than a size threshold).
Quick reference: common imageData keys Recap
  • Kyverno’s imageRegistry context gives you a window into the container image: manifest and config.
  • Use it to inspect config.User (and other fields like Env, Entrypoint) and enforce policies that depend on image internals, not just the Pod manifest.
  • Use jmesPath to extract or compute values from the fetched JSON for more advanced validations.
The image is a summary list of four key features related to image data and policies, including new context, rich data, powerful validations, and advanced transformation. Each feature is numbered and briefly explained.
You are now equipped to write Kyverno policies that pull image metadata from registries, enabling more intelligent, context-aware admission controls. Links and references

Watch Video