Kubernetes v1.33 promotes Image Volumes from alpha to beta. This feature let you mount image layers as native volumes inside pods. You get granular file access without rebuilding containers or custom init logic. In v1.33, the feature still requires explicit enabling. CRI-O and containerd runtimes now support the beta API. This article covers end-to-end details: feature gates, pod spec, lifecycle, access modes, security context, quotas, CSI integration, snapshots, and event-driven patterns for advanced use cases.
TL;DR
- Image Volumes mount image layers as ephemeral volumes in pods.
- v1.33 promotes the feature to beta; disabled by default.
- Enable via feature-gates:
ImageVolume. - Supports readOnlyMany and readWriteOnce modes; no CSI driver required.
- Works with CRI-O v1.33+ and containerd v2+.
- Suitable for multi-tenant caching, dynamic config injection, event-driven file exports.
What are Image Volumes?
Image Volumes let you mount individual layers or mountpoints from OCI images directly into a container filesystem. You no longer need pre-packaged emptyDir or hostPath mounts for transient data stored at build time. It behaves like ephemeral volumes: they appear when a pod starts, persist during container execution, and vanish when the pod terminates. You can mount layers as read-only or enable copy-on-write for writeable layers.
Image Volumes in v1.33 Beta
v1.33 graduates Image Volumes to beta, signalling stability in API and runtime interactions. The feature remains disabled by default since not all CRI runtimes implemented beta semantics. CRI-O supports the beta API in v1.33; containerd merged support behind ImageVolume feature-gate and targets v2 release compatibility.
Enabling The Feature
Enable Image Volumes in your kube-apiserver, kube-controller-manager, kube-scheduler, kubelet, and CRI runtime settings. Use the --feature-gates=ImageVolume=true flag:
# For kubelet
kubelet --feature-gates=ImageVolume=true \
--container-runtime=remote \
--container-runtime-endpoint=unix:///run/crio/crio.sock
# For containerd
containerd --feature-gates ImageVolume=true
Once enabled, the API exposes a new imageVolume volume type in pod specs.
Pod Spec Example
apiVersion: v1
kind: Pod
metadata:
name: image-volume-demo
spec:
volumes:
- name: app-files
imageVolume:
image: nginx:1.25.1
mountPath: /app/html
readOnly: true
containers:
- name: web-server
image: busybox
command: ['sh','-c','ls -l /app/html']
volumeMounts:
- name: app-files
mountPath: /app/html
readOnly: true
This mounts the /usr/share/nginx/html layer files from the nginx image to /app/html in the busybox container. You can override mountPath to any directory inside the container.
Image Volume Lifecycle and Claims
Image Volumes follow the standard volume lifecycle: Bound when the pod schedules, available through the container runtime, and released when the pod terminates. They do not require PVC or StorageClass. There is no persistent claim: capacity is implicitly the size of the image layer. You cannot resize or snapshot directly.
Access Modes and Security Context
Image Volumes support two access modes:
- readOnly: Default. Mounts the image as read-only layers. Suitable for static content and shared caches.
- copyOnWrite: Optional. Creates an ephemeral overlay with read-write support. Data persists only for pod lifetime.
You can set securityContext at volumeMount or container level to restrict user and group IDs:
securityContext:
runAsUser: 1001
fsGroup: 2001
Linux security contexts ensure these volumes adhere to PodSecurityPolicies and seccomp profiles.
Capacity, Quotas, and Resource Tracking
Since Image Volumes mount pre-existing image layers, they consume no additional cluster storage quota until copyOnWrite mode writes data. The kubelet tracks ephemeral storage usage per Pod. You can set ephemeral-storage requests and limits in container resource specs:
resources:
requests:
ephemeral-storage: "50Mi"
limits:
ephemeral-storage: "100Mi"
This prevents runaway writes in copy-on-write volumes and enforces fair resource usage across pods.
Snapshots and CSI Integration
Alpha implementations considered CSI drivers for image layers. In beta, Kubernetes does not require a CSI driver for Image Volumes. You cannot create VolumeSnapshot for these volumes. If you need advanced snapshotting, build a CSI plugin that wraps imageVolume APIs or convert image layers to PVC-backed volumes.
Image Volumes Use Cases
Image Volumes open new patterns in event-driven and multi-tenant architectures:
- Multi-tenant Static Content: Mount front-end assets from a base image. No need to bake assets into each container build.
- Dynamic Configuration: Mount configuration files from a utility image. Applications read fresh configs without updating their image.
- Serverless Functions: Mount function code from OCI images at runtime to isolate user code in ephemeral volumes. Combine with Knative to drive event-based deployments.
- Data Export Flow: A CI pipeline image contains reporting scripts. Mount that image into a reporting pod that pulls raw data, generates reports, and pushes to storage.
Troubleshooting and Best Practices
If your pod fails to mount the image volume, verify the feature gate in all control-plane components and runtimes. Check CRI-O or containerd logs for errors about unsupported features. Confirm image references and tag accuracy. Use kubectl describe pod to inspect volume events.
For production, limit copy-on-write volumes to scenarios that need write-access. Use readOnly mode for static assets to reduce ephemeral storage pressure.
Future Roadmap for Image Volumes
The Kubernetes community plans to stabilize Image Volumes in GA (v1.35+). Upcoming enhancements include:
- VolumeSnapshot support via CSI.
- StorageClass integration for remote OCI registries.
- Cross-namespace imageVolume mounts for multi-tenant isolation.
- Extended security policies for imageVolume FS layers.
References
- Kubernetes Blog: v1.33 Image Volume Beta
- KEP-4639: Image Volume
- Kubernetes Feature Gates
- CRI-O Project
- containerd
Suggested Reading
PostHashID: 0ad3e8c2cd2759853c2be9c9321d4636f31b54957d11ccd31a0451428b1d135c
