feat(docker): supply CDI context for GPU sandboxes

Signed-off-by: Evan Lezar <elezar@nvidia.com>

Author: elezar

architecture/compute-runtimes.md

@@ -169,6 +169,17 @@ Resource requirements enter the driver layer through `SandboxSpec.resource_requi
 can request a specific number of GPUs or the driver-specific default behaviour.
 For all in-tree drivers, this is equivalent to selecting a single GPU.
 
+For Docker GPU sandboxes, the driver treats CDI specs as runtime metadata for
+both outer injection and inner sandbox policy. It selects opaque CDI device IDs,
+passes them to Docker, mounts daemon-reported CDI spec directories into
+supervisor-only paths, and uploads a versioned CDI context before starting the
+container. The supervisor resolves that context inside the sandbox and derives
+Landlock paths and supplemental groups from CDI `containerEdits`. Host-side CDI
+spec paths are diagnostic only and are never treated as sandbox policy paths.
+Kubernetes must not infer CDI device IDs from the `nvidia.com/gpu` resource
+request; it needs a node-local selected-device handoff before using the same
+supervisor resolver.
+
 VM runtime state paths are derived only from driver-validated sandbox IDs
 matching `[A-Za-z0-9._-]{1,128}`. The gateway-owned VM driver socket uses a
 private `run/` directory plus Unix peer UID/PID checks. Standalone

crates/openshell-core/src/cdi.rs

@@ -9,12 +9,21 @@ use serde::{Deserialize, Serialize};
 
 pub const CDI_CONTEXT_VERSION: u32 = 1;
 
+/// File name used for the serialized CDI context.
+pub const CDI_CONTEXT_FILE_NAME: &str = "cdi-context.json";
+
 /// Absolute supervisor path for the CDI context file mounted by a compute driver.
 pub const CDI_CONTEXT_PATH: &str = "/run/openshell/supervisor/cdi-context.json";
 
 /// Base supervisor path under which compute drivers mount CDI specification directories.
 pub const CDI_SPEC_DIR_BASE: &str = "/run/openshell/supervisor/cdi-specs";
 
+/// Return the supervisor path used for a CDI specification directory.
+#[must_use]
+pub fn cdi_spec_mount_path(index: usize) -> String {
+    format!("{CDI_SPEC_DIR_BASE}/{index}")
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct CdiContext {
     pub version: u32,

crates/openshell-driver-docker/Cargo.toml

@@ -24,10 +24,10 @@ serde_json = { workspace = true }
 prost-types = { workspace = true }
 bollard = { version = "0.20" }
 url = { workspace = true }
+tar = "0.4"
 
 [dev-dependencies]
 prost-types = { workspace = true }
-tar = "0.4"
 temp-env = "0.3"
 tempfile = "3"
 

crates/openshell-driver-docker/README.md

@@ -86,9 +86,33 @@ contract:
 | `restart_policy = unless-stopped` | Keeps managed sandboxes resumable across daemon or gateway restarts. |
 | `PidsLimit` | Enforces the sandbox PID budget at the Docker cgroup layer. Set `[openshell.drivers.docker].sandbox_pids_limit = 0` to inherit the Docker/runtime default. |
 | CDI GPU request | Uses opaque `driver_config.cdi_devices` values when set; otherwise selects the requested count of NVIDIA CDI GPUs in round-robin order when daemon CDI support is detected. Docker daemon `/info` can permit `nvidia.com/gpu=all` as a WSL2 all-only compatibility fallback, where it counts as one selectable device. Exact CDI device lists must not contain duplicates and must match the effective GPU count. |
+| CDI context upload | For GPU/CDI sandboxes only, mounts daemon-reported CDI spec directories read-only under `/run/openshell/supervisor/cdi-specs/<n>` and uploads `/run/openshell/supervisor/cdi-context.json` after container create and before start. |
 
 The agent child process does not retain these supervisor privileges.
 
+## CDI GPU Metadata
+
+Docker remains the source of truth for GPU injection. The driver selects opaque
+CDI device IDs from `driver_config.cdi_devices` or the daemon's discovered CDI
+inventory, then passes the same IDs to Docker with a CDI `DeviceRequest`.
+
+When a GPU/CDI request is present, the driver also mounts the Docker
+daemon-reported `Info.CDISpecDirs` into supervisor-only paths and uploads a
+small versioned CDI context through Docker's container archive API. The context
+uses container-side spec paths for resolution and keeps host-side spec sources
+diagnostic-only. If the upload fails, the driver removes the created container
+and sandbox token file before reporting the failure.
+
+The sandbox supervisor resolves the selected IDs from those mounted specs
+before it launches agent processes. CDI device nodes become read-write
+Landlock paths, mount destinations default to read-only paths, and
+`additionalGids` become supplemental groups for the entrypoint and SSH child
+processes. Writable CDI mount destinations are accepted only for exact
+single-file paths already listed in the sandbox policy `read_write` list;
+writable CDI directory mounts fail closed. Kubernetes, Podman, WSL2 hardware
+validation, and Tegra/Jetson hardware validation are separate follow-up
+targets.
+
 ## Driver Config Mounts
 
 The gateway forwards the `docker` block from `--driver-config-json` to this