# Kubernetes v1.33: Image Volumes Graduate to Beta
> Kubernetes v1.33 promotes Image Volumes to beta, letting OCI artifacts mount directly into pods as read-only volumes, boosting portability and efficiency.

Canonical: https://blog.abhimanyu-saharan.com/posts/kubernetes-v1-33-image-volumes-graduate-to-beta
Published: 2025-05-04
Last updated: 2025-05-24
Authors: Abhimanyu Saharan
Categories: Kubernetes v1.33, Kubernetes

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:

```plaintext
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](https://github.com/containerd/containerd/pull/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](https://github.com/kubernetes/enhancements/issues/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.

## FAQ

### What are Image Volumes in Kubernetes?

Image Volumes allow Kubernetes pods to mount an OCI image as a read-only volume. This separates executable logic from static data, enabling cleaner delivery of models, binaries, or config files without embedding them in the application container.

### What use cases are Image Volumes best suited for?

They are ideal for scenarios like:

- Serving ML models without bundling them in the container
- Distributing signed config files securely
- Loading proprietary data (e.g., malware signatures) into scanners  
These use cases benefit from clean, OCI-native data delivery.

### What improvements are included in the Kubernetes v1.33 beta release of Image Volumes?

v1.33 introduces support for `subPath` and `subPathExpr`, allowing you to mount specific subdirectories of an image volume. It also adds kubelet metrics for tracking usage and mount success/failure.

### Which container runtimes support Image Volumes as of v1.33?

- **CRI-O**: Supports Image Volumes in beta starting with v1.33.
- **containerd**: Has merged alpha support and is actively developing beta compatibility.  
The feature must be manually enabled via the `ImageVolume` feature gate.

### What are the key implementation details developers should know?

- Mounts are read-only and `noexec`
- Pull behavior aligns with container image pulls and supports pull secrets
- Compatible with the `AlwaysPullImages` admission controller
- Uses standard container image layer mechanisms for mounting