fix(docker): document CDI context mount

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

Author: elezar

architecture/compute-runtimes.md

@@ -245,10 +245,11 @@ 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.
+supervisor-only paths, and bind-mounts a gateway-owned versioned CDI context
+read-only before creating 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.

crates/openshell-driver-docker/Cargo.toml

@@ -38,13 +38,13 @@ miette = { workspace = true }
 toml = { workspace = true }
 tower-http = { workspace = true }
 http = { workspace = true }
-tar = "0.4"
 
 [dev-dependencies]
 openshell-otel-test-support = { path = "../openshell-otel-test-support" }
 opentelemetry = { workspace = true }
 opentelemetry_sdk = { workspace = true, features = ["testing"] }
 prost-types = { workspace = true }
+tar = "0.4"
 temp-env = "0.3"
 tempfile = "3"
 tracing-subscriber = { workspace = true }

crates/openshell-driver-docker/README.md

@@ -107,7 +107,7 @@ contract:
 | `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. |
 | `policy-dns-transparent-tcp` capability | Declares that the combined Docker supervisor can own namespace-local DNS/TCP capture and coupled workload restart. The shared supervisor still owns DNS eligibility, mappings, authorization, pinned dialing, relaying, and OCSF decisions. The marker is stripped from the workload environment. |
-| 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. |
+| CDI context mount | For GPU/CDI sandboxes only, creates a gateway-owned context file and bind-mounts it read-only at `/run/openshell/supervisor/cdi-context.json`; daemon-reported CDI spec directories are mounted read-only under `/run/openshell/supervisor/cdi-specs/<n>`. |
 
 The agent child process does not retain these supervisor privileges.
 
@@ -118,11 +118,13 @@ 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.
+daemon-reported `Info.CDISpecDirs` into supervisor-only paths. Before container
+creation, it writes a small versioned CDI context in gateway-owned state and
+bind-mounts it read-only into the supervisor. The context uses container-side
+spec paths for resolution and keeps host-side spec sources diagnostic-only. If
+context or token creation fails, the driver removes any created state files; if
+container creation or start fails, it also removes the container and state
+files 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

docs/reference/sandbox-compute-drivers.mdx

@@ -170,11 +170,13 @@ For GPU-backed Docker sandboxes, configure Docker CDI before starting the gatewa
 For Docker GPU/CDI sandboxes, OpenShell uses Docker's selected CDI device IDs
 and daemon-reported CDI spec directories to build a supervisor-only CDI
 context. The driver mounts the spec directories read-only into the sandbox
-container, uploads `cdi-context.json` before starting the container, and removes
-the created container if that upload fails. The supervisor resolves the context
-inside the sandbox and derives the inner filesystem and supplemental group
-requirements from CDI specs. Non-GPU Docker sandboxes do not receive the CDI
-context, spec mounts, or CDI-derived policy changes.
+container. Before creation, it writes a gateway-owned `cdi-context.json` and
+bind-mounts it read-only into the supervisor. If context or token creation
+fails, the driver removes the created state files; if container creation or
+start fails, it also removes the container and state files. The supervisor
+resolves the context inside the sandbox and derives the inner filesystem and
+supplemental group requirements from CDI specs. Non-GPU Docker sandboxes do not
+receive the CDI context, spec mounts, or CDI-derived policy changes.
 
 ### Docker Driver Config Mounts