Skip to content

runtime: Support OCI image volume type (KEP-4639 / VolumeSource.image) #13749

Open

Description

@vvoronko

Problem / Feature Gap

Kata Containers does not yet support the OCI image volume source type introduced in KEP-4639 (Kubernetes 1.31+, ImageVolume feature gate). When a pod spec includes a volumes[].image source and is scheduled onto a kata runtime, container creation fails with ENOENT - the kata shim has no path to mount inside the VM guest for this volume type.

Concrete example

The openshell-supervisor-bin volume in the openshell SandboxTemplate is declared as an image volume:

{
"image": {
"pullPolicy": "IfNotPresent",
"reference": "ghcr.io/nvidia/openshell/supervisor:8d67250a5d17348eb96c4fa46226b06d8041f2ba"
},
"name": "openshell-supervisor-bin"
}

This mounts the OCI image read-only at /opt/openshell/bin. The container entrypoint /opt/openshell/bin/openshell-sandbox depends on this volume being present.

Why it works with runc, but not kata

With runc, image volumes are handled by the node-level container runtime (CRI-O / containerd): the image is pulled and its root filesystem is bind-mounted into the container's mount namespace on the host. No special shim-level support is needed.

With kata, the container runs inside a VM. The kata shim must pass the image volume contents into the guest (e.g. via virtio-fs). Since kata does not yet implement this volume type, container creation fails with the following pod event:

Error: CreateContainer failed: ENOENT: No such file or directory
Stack backtrace:
0:
...
10: __libc_start_call_main
11: __libc_start_main@GLIBC_2.2.5
12:
Stack backtrace:
0:
...
22: start_thread
23: __clone3: unknown

Describe the solution you'd like

Kata should implement support for VolumeSource.image by pulling (or reusing an already-pulled) OCI image on the host side and exposing its contents inside the VM guest - most naturally via virtio-fs, consistent with how other read-only host-backed volumes are handled today.

Describe alternatives you've considered

Init container + emptyDir workaround: replace the image volume with an init container that copies the binary from the same OCI image into an emptyDir, which is then mounted at the target path. This works today but requires kata-specific changes in the consumer (openshell SandboxTemplate or an admission webhook), which is not a scalable solution as adoption of VolumeSource.image grows.

Additional context

  • ImageVolume feature gate was Alpha in Kubernetes 1.31, Beta in 1.32+, making this increasingly common in newer OpenShift / Kubernetes clusters.
  • The failure is silent in the sense that the pod spec is valid and accepted by the API server; the error only surfaces at container creation time inside the kata shim.
  • This affects any workload that relies on image volumes to deliver binaries or configuration into a sandbox - a pattern that is likely to grow as the feature matures.

Before raising this feature request

Checked the limitations document - VolumeSource.image is not listed there.

Activity

  1. manuelh-dev commented on Aug 28, 2026

    @manuelh-dev
    Contributor

    @vvoronko, thanks for opening this. If this topic gains traction, I'd be interested in this KEP for the Kata scenarios where filesystem sharing is disabled.

  2. vvoronko commented on Aug 28, 2026

    @vvoronko
    ContributorAuthor

    @manuelh-dev FYI, after some investigation found out that although KEP-4639 is titled "OCI Artifact and/or Image VolumeSource", upper-level CRI runtimes (containerd and CRI-O) currently only support standard OCI Container Images.
    If you attempt to use VolumeSource.image with a generic OCI Artifact (an image with an empty config or non-standard media types), containerd fails at the CRI level before it even invokes runsc or kata, throwing: failed to unpack image on snapshotter overlayfs: mismatched image rootfs and manifest layers.
    This limitation is tracked in containerd/containerd#11381 and cri-o/cri-o#8953.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    featureNew functionalityneeds-reviewNeeds to be assessed by the team.

    Type

    No type

    Fields

    Priority

    None yet

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions