Kubernetes v1.33: Image Volumes Beta with subPath Support

In the Kubernetes v1.33 release, Image Volumes—originally introduced as an Alpha feature in v1.31 under KEP-4639—now graduate to Beta. This milestone ushers in improved stability, richer subPath handling, and expanded runtime support, setting the stage for broader production adoption in container-native storage patterns.

Feature Status and Runtime Compatibility

Although Beta-graded, Image Volumes remain disabled by default via the ImageVolumes feature gate. Administrators must explicitly enable this gate to experiment or roll out the capability in production clusters. The current runtime compatibility is as follows:

• CRI-O: Alpha support since v1.31; full Beta support landed in v1.33.
• containerd: Alpha merge in PR #10579, shipping in v2.1.0. Beta support progressing under PR #11578.
• Docker Engine (dockershim): Deprecated in Kubernetes; community contributions are welcome.
• Other CRI-compliant runtimes: Adoption and integration depend on individual SIG and vendor priorities.

What’s New in Beta

The key enhancement for Beta is subPath and subPathExpr support on Image Volumes. New validations and mount semantics include:

• noexec readonly mounts: Image Volumes preserve immutability and prevent code execution from image layers, aligning with hardened container security practices.
• Strict path sanitation: Kubernetes and runtimes now reject absolute paths or sequences like ../ to eliminate directory traversal exploits.
• Runtime error feedback: If the target subdirectory does not exist, container creation fails with clear kubelet events and pod status messages.
• Consistent metrics: Three new kubelet counters enable monitoring adoption and reliability:

• kubelet_image_volume_requested_total
• kubelet_image_volume_mounted_succeed_total
• kubelet_image_volume_mounted_errors_total

Technical Deep Dive: subPath Implementation

Under the hood, Image Volumes leverage the container runtime’s layer mount API to expose a specific filesystem subtree without extracting the full image. This saves disk I/O and reduces startup latency. When subPath is specified, Kubernetes invokes the runtime’s Mount operation with a --source-layer flag, slicing the layer snapshot via overlay mounts. The noexec,ro mount flags are injected at mount time by the kubelet, ensuring end-to-end immutability from image registry to pod namespace.

Container Runtime Support Matrix

Runtime support for Image Volumes has been tracked by SIG Node and community contributors:

• CRI-O v1.31+: Alpha; v1.33: Beta complete with subPathExpr expansions.
• containerd v2.1.0: Alpha features available now; v2.2.x will include stable --subpath flags and new ImageVolumeManager plugin architecture.
• Windows container scenarios: Experimental prototype under discussion, tracking KEP-5099.

Usage Example

Below is an illustration of mounting a specific directory named dir from a container image:

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

Apply and inspect:

kubectl apply -f image-volumes-subpath.yaml
kubectl attach -it image-volume-subpath -- /bin/bash
cat /mnt/data/file

Expert Perspectives and Best Practices

“Image Volumes in Beta are a significant leap toward immutable, container-centric storage,” says Michelle Au, Principal Engineer at a leading cloud provider. “We recommend enabling the feature gate in staging clusters, instrumenting the new metrics, and verifying runtime compliance via kubelet logs.”

Key recommendations:

• Enable --feature-gates=ImageVolumes=true only after assessing runtime readiness.
• Use subPathExpr for dynamic mounts driven by environment variables, e.g. subPathExpr: "${POD_NAME}-logs".
• Monitor kubelet_image_volume_mounted_errors_total to detect missing paths early in your CI/CD pipelines.

Roadmap and Further Reading

Looking ahead to Kubernetes v1.34 and beyond, SIG Node is evaluating:

• Writable overlay support for advanced build and debug workflows.
• Direct OCI layer selection via annotations, bypassing full image pulls.
• Integration with CSI drivers for cross-region image volume replication.

Further reading

• Use an Image Volume With a Pod
• image volume overview
• KEP-4639 (tracking design and implementation)