google / google/gvisor

runsc: Support Kubernetes OCI VolumeSource (KEP-4639 / VolumeSource.image)

Open
#14,471 2 comments 0 reactions 0 assignees View on GitHub
type: enhancement
Dominant language
Go
Stars
19.3k
Forks
2k
Avg merge
3d 5h
Merged PRs (30d)
264

Description

### Description

## Feature Request

### Problem Description
In Kubernetes 1.31+, pods can use OCI image volumes (`VolumeSource.image` / KEP-4639) to mount container images or artifacts read-only directly into a container path without baking them into the main container image.

When running a workload that uses `VolumeSource.image` (such as NVIDIA OpenShell or CNCF `agent-sandbox`) using `runsc` as the CRI handler, container creation fails.

The CRI layer (CRI-O / containerd) pulls and unpacks the target image into a local host snapshotter directory and passes the mount specification to `runsc`. However, the `runsc` shim does not configure the Gofer file proxy process to expose this host snapshotter directory to the Sentry kernel. Because the host path is never proxied into the sandbox, the entrypoint binary inside the mounted path cannot be found, causing startup to fail.

### Error Output
```text
Error: failed to start container agent: `/usr/local/bin/runsc-crio --root /run/runsc --systemd-cgroup start agent` failed:
starting container: starting root container: starting sandbox: creating process: failed to load /opt/openshell/bin/openshell-sandbox: no such file or directory : exit status 128
```

### Steps to Reproduce
Deploy a Pod using runtimeClassName: gvisor (or runsc) with an image volume definition:

```text
apiVersion: v1
kind: Pod
metadata:
name: image-volume-test
spec:
runtimeClassName: gvisor
containers:
- name: sandbox
image: ghcr.io/nvidia/openshell/sandbox:latest
command: ["/opt/openshell/bin/openshell-sandbox"]
volumeMounts:
- name: openshell-supervisor-bin
mountPath: /opt/openshell/bin
volumes:
- name: openshell-supervisor-bin
image:
reference: ghcr.io/nvidia/openshell/supervisor:8d67250a5d17348eb96c4fa46226b06d8041f2ba
pullPolicy: IfNotPresent`
```

### Expected Behavior
The runsc CRI shim should recognize host snapshotter mount points generated for KEP-4639 image volumes by CRI-O or containerd, and instruct the Gofer process to proxy the unpacked read-only host directory into the Sentry filesystem tree.

### Context & References
Kubernetes KEP: [KEP-4639: OCI VolumeSource](https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/4639-oci-volume-source)

Related Issue (Kata Containers): [kata-containers/kata-containers#13749](https://github.com/kata-containers/kata-containers/issues/13749)

### Environment
* **gVisor Component:** `runsc` / `containerd-shim-runsc-v1`
* **Kubernetes Version:** 1.31+
* **CRI Runtime:** CRI-O / containerd with KEP-4639 enabled

### Is this feature related to a specific bug?

_No response_

### Do you have a specific solution in mind?

_No response_

Contributor guide

Open the contributing guide

Research direction

Start at the runsc CRI shim's handling of mount specifications and trace how it configures the Gofer file proxy and Sentry filesystem for containerd or CRI-O image-volume paths. Reproduce the Kubernetes 1.31+ VolumeSource.image example, then verify that the read-only volume is visible and its mounted entrypoint starts under runsc.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, kubernetes
Domain
infrastructure, operating-systems
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.