Kubernetes v1.33: Image Volumes Graduate to Beta

In Kubernetes v1.33, the Image Volume feature moves from alpha to beta—marking a major step toward enabling cleaner, container-native ways of managing read-only content in pods. While still disabled by default (due to ongoing runtime support gaps), the functionality is powerful enough to warrant early exploration, especially if you deal with model packaging, binary artifact delivery, or configuration management in your workloads.

In this post, we’ll walk through what Image Volumes are, what’s new in the beta release, and how you might use them in real-world scenarios.

What Are Image Volumes?

Image Volumes allow you to mount an OCI image (or artifact) as a read-only volume inside a Kubernetes pod. Instead of bundling static content (like configuration files, machine learning models, or malware signatures) directly inside your main application container, you can:

Build a separate OCI artifact containing only the files you want
Push it to a registry (just like any other container image)
Mount it into your pod using the volumes.image.reference field

This clean separation between executable logic and passive data reduces image size, improves reuse, and better supports secure, composable workloads.

Why Does It Matter?

This feature is especially relevant for the growing set of Kubernetes users in the AI/ML, DevSecOps, and artifact distribution spaces.

Some practical use cases include:

Mounting ML model weights from a pre-packaged artifact without baking them into your model server image
Distributing signed configuration files from a central registry to multiple pods securely
Loading proprietary malware signatures into a public scanner image without rebuilding it

Until now, options to achieve these patterns were either clunky (init containers copying files), insecure (custom hostPath volumes), or hard to manage at scale (ConfigMaps with binary blobs). Image Volumes provide a clean, OCI-native alternative.

What’s New in the Beta?

With v1.33, the feature now supports subPath and subPathExpr within volumeMounts. This lets you mount a specific subdirectory from the image volume into the container. It's a small but important change—it gives you finer control over which part of the image is exposed, avoiding unnecessary content being visible to the container.

Here's a quick example:

apiVersion: v1
kind: Pod
metadata:
  name: image-volume
spec:
  containers:
  - name: shell
    image: debian
    command: ["sleep", "infinity"]
    volumeMounts:
    - name: volume
      mountPath: /volume
      subPath: dir
  volumes:
  - name: volume
    image:
      reference: quay.io/crio/artifact:v2
      pullPolicy: IfNotPresent

This mounts the contents of dir from the referenced image into /volume in the container.

Important: Subdirectories must already exist in the image volume. If not, the container will fail to start and kubelet will report the error using standard events.

Metrics You Can Now Monitor

Three new kubelet metrics are introduced for observability:

kubelet_image_volume_requested_total – Tracks how often an image volume is requested.
kubelet_image_volume_mounted_succeed_total – Counts successful mounts.
kubelet_image_volume_mounted_errors_total – Tracks failed mount attempts.

These are useful for cluster admins who want visibility into how image volumes are being used and where failures may be occurring.

Runtime Compatibility

As of v1.33:

CRI-O supports image volumes in beta, starting from v1.33.
containerd has merged alpha support and is actively working on beta support in PR #11578.

This means you may still need to enable the feature gate manually (ImageVolume=true) on your API server and kubelet, and ensure your runtime is up to date.

Implementation Details You Should Know

OCI artifacts are merged and mounted using the same mechanisms as standard container image layers.
The mount is read-only and noexec by design.
Pull behavior respects pullPolicy, and behaves exactly like image pulls for containers.
Pod recreation re-resolves the volume and pulls fresh content if necessary.
Pull secrets are supported in the same way as for containers.
The feature is compatible with the AlwaysPullImages admission controller.
If :latest is used, default pullPolicy is Always; otherwise, it’s IfNotPresent.

Who Should Try This?

If you’re:

Running Kubernetes in environments that rely on immutable infrastructure
Working in AI/ML and want to separate models from serving code
Maintaining high-security pipelines where trusted content should not be baked into application containers
Building CI/CD workflows that push artifacts to OCI registries

…then Image Volumes may be a clean, scalable fit for your architecture.

What’s Next?

The SIG Node team is actively working toward feature stabilization and wider runtime support. We expect more feedback, real-world adoption, and additional use cases to emerge as the beta matures. If you're interested, get involved:

Join the conversation on Kubernetes Slack: #sig-node
Track progress via KEP-4639
Test it out and report issues early

Final Thoughts

With Image Volumes now in beta, Kubernetes is one step closer to treating container images as composable file systems—a move that better aligns with how modern infrastructure teams are designing pipelines and managing content.

Even though it’s still behind a feature gate, this is the right time to start testing the feature, identifying blockers, and preparing your workloads for the eventual GA.

Thanks to everyone involved in the community who helped drive this forward.