Skip to content

Commit b724cc8

Browse files
committed
docs(gpu): explain CDI upgrade requirements
Signed-off-by: Evan Lezar <elezar@nvidia.com>
1 parent 3a623cf commit b724cc8

3 files changed

Lines changed: 28 additions & 9 deletions

File tree

‎docs/how-it-works/policies/default-policy.mdx‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -119,11 +119,13 @@ launch or exec. They do not add filesystem grants or parent directory access and
119119
do not require `read_write` entries, regardless of mount flags. Communication
120120
uses the existing Unix IPC and socket permission checks.
121121

122-
Ordinary writable CDI mount destinations are fail-closed. OpenShell accepts a writable
123-
CDI mount only when it targets a single file and that exact path is already
124-
listed in `filesystem_policy.read_write`. Writable CDI directory mounts and CDI
125-
paths such as `/`, `/dev`, `/proc`, `/sys`, `/run`, or `/usr` are rejected
126-
during sandbox startup.
122+
Ordinary CDI file and directory mounts must be effectively read-only. OpenShell
123+
rejects writable mounts even when `filesystem_policy.read_write` names their
124+
exact destination or an ancestor. Explicit authorization for CDI host writes is
125+
not currently supported. This restriction does not apply to device nodes or
126+
Unix socket communication.
127+
CDI paths such as `/`, `/dev`, `/proc`, `/sys`, `/run`, or `/usr` remain rejected
128+
during sandbox startup, even when authored policy grants access to those roots.
127129

128130
CDI does not add a blanket `/sys` grant. If an application needs sysfs paths
129131
that the selected CDI spec does not supply, include those paths in your authored

‎docs/how-it-works/sandboxes/overview.mdx‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -158,12 +158,14 @@ updated Docker daemon capability.
158158
For CDI-enabled Docker sandboxes, OpenShell validates the injected filesystem
159159
targets before each launch and exec. Library directories may use symlinks, but
160160
must not resolve to broad roots such as `/`, `/usr`, or `/dev`. Device nodes must
161-
resolve to devices, and ordinary writable mounts must resolve to single files explicitly
162-
allowed by exact entries in the policy. OpenShell determines mount access from
161+
resolve to devices. Ordinary file and directory mounts must be effectively
162+
read-only; writable mounts are rejected even with exact or ancestor authored
163+
write grants. Explicit authorization for CDI host writes is not currently
164+
supported. OpenShell determines mount access from
163165
effective runtime flags, including writable submounts beneath original directory
164166
mounts. Unix socket mounts retain their exact socket destinations and must resolve
165167
to sockets at each launch or exec. They do not grant access to parent directories
166-
or require writable-file policy entries. CDI does not automatically grant write access to `/proc`. The container
168+
or require writable filesystem grants. CDI does not automatically grant write access to `/proc`. The container
167169
runtime must supply any supplemental groups required by the CDI spec; missing
168170
groups prevent workload launch. CDI spec projections are checked with resource
169171
admission enabled. Invalid CDI targets or unavailable filesystem enforcement

‎docs/how-it-works/sandboxes/runtimes.mdx‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,12 @@ and daemon-reported CDI spec directories to build a workload CDI context. The
126126
driver embeds the context in the protected boundary configuration and
127127
projects the spec directories read-only under the protected `/.openshell/cdi-specs`
128128
hierarchy. These structured binds neither create missing host directories nor
129-
relabel existing directories. Every daemon-reported directory must exist and be
129+
relabel existing directories. Before creating a GPU sandbox, OpenShell checks each directory with a temporary,
130+
stopped container using the prepared workload image. It skips confirmed missing
131+
directories and records only the available projections. Probe results are cached
132+
for 30 seconds and refreshed on demand; sandbox creation is not retried.
133+
At least one directory must remain and every selected device must resolve from
134+
its specs. Permission errors still fail creation; existing directories must be
130135
readable under the host's SELinux policy. Agent processes cannot read the
131136
projections, even with a broad authored filesystem grant. If context
132137
creation fails, the driver removes the created state. If workload or supervisor
@@ -136,6 +141,16 @@ requirements from CDI specs before launching agent processes. Non-GPU Docker
136141
sandboxes do not receive the CDI context, spec mounts, or CDI-derived policy
137142
changes.
138143

144+
Existing Docker GPU containers without CDI context retain the legacy GPU
145+
filesystem baseline on restart. Admission requires spec projections only when
146+
the driver-owned boundary configuration contains CDI context, and validates
147+
those projections against the directories recorded at creation. Missing or
148+
unreadable boundary configuration blocks restart. To use CDI-derived access on
149+
an older sandbox, recreate it. Ordinary CDI file and directory mounts must be
150+
effectively read-only. Filesystem `read_write` grants do not authorize writable
151+
CDI mounts; explicit authorization for CDI host writes is not currently
152+
supported. Device nodes and Unix socket communication remain supported.
153+
139154
### Docker Corporate Proxy Egress
140155

141156
For proxy-required networks, the Docker driver accepts `https_proxy`,

0 commit comments

Comments
 (0)