feat(docker): supply CDI context for GPU sandboxes

[elezar]

Summary

Provide the Docker-side CDI producer for GPU sandboxes: discover CDI support, select devices, bind-mount a gateway-owned CDI context and daemon-reported specs read-only, and clear CDI state for non-GPU containers. This is the final PR in the #1606 stack.

Related Issue

Part of #1606. Depends on #2776.

Changes

• Add Docker CDI runtime discovery, GPU selection, and read-only CDI spec mounts.
• Create the driver-owned CDI context before container creation and bind-mount it read-only into the supervisor.
• Clear CDI context for non-GPU containers and clean context and token state after failed provisioning.
• Document the Docker CDI lifecycle and add Docker-focused coverage.

Testing

• mise run pre-commit passes.
• Focused core CDI and Docker driver unit tests pass.
• E2E tests added/updated (CI GPU E2E remains required).

Checklist

• Follows Conventional Commits.
• Commits are signed off (DCO).

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-2265.docs.buildwithfern.com/openshell

[github-actions]

Label test:e2e-gpu applied for 5cd240a. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute GPU E2E after building the required supervisor image once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

[github-actions]

Label test:e2e applied for 5cd240a. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

[elezar]

gator-agent

PR Review Status

Validation: This PR is project-valid because it implements roadmap issue #1606 for Docker GPU/CDI sandbox policy derivation, includes user-facing documentation, and has the required E2E/GPU E2E labels.
Head SHA: c040b8dd5d7adcb126d1c5199e6203ba5dfdc93b

Thanks @drew, I checked the CDI context trust-boundary concern you raised and confirmed it is still a blocking issue on this head. The independent review also found related supervisor-side hardening gaps and a Docker token cleanup regression.

Review findings:

• Blocking findings remain on CDI context trust, CDI device-node validation, and failed-provisioning token cleanup.

Docs: Fern docs were updated under docs/; no navigation change appears necessary for these existing pages.
Checks: Required checks are currently green, including DCO, Branch Checks, Helm Lint, Core E2E, and GPU E2E.
E2E: test:e2e and test:e2e-gpu are applied and passing.

Next state: gator:in-review

[elezar]

gator-agent

PR Review Status

Validation: This PR is project-valid because it implements roadmap issue #1606 for Docker GPU/CDI sandbox policy derivation, includes architecture and Fern documentation updates, and has the required test:e2e and test:e2e-gpu labels.
Head SHA: cf6a99519f85611da0558468ce42f84c6940976d

Thanks @drew, I re-checked the CDI context trust-boundary concern you raised against the latest head. The Docker env cleanup and token cleanup paths are improved, but the independent review found the supervisor still needs a stronger driver-attestation boundary before CDI-derived policy is trusted.

Review findings:

• Blocking finding remains on CDI context trust/attestation.
• Warning remains on explicit CDI device ID namespace validation.

Docs: Fern docs were updated under docs/; no navigation change appears necessary for these existing pages.
Checks: Current head has DCO and Helm Lint passing, with Branch Checks, E2E, and GPU E2E still pending/queued.
E2E: test:e2e and test:e2e-gpu are applied; results are still pending for this head.

Next state: gator:in-review

[elezar]

gator-agent

Warning: The selected IDs passed into the CDI context can come from explicit driver_config.cdi_devices, and current validation only checks count/duplicates, not that each ID is in the NVIDIA GPU CDI namespace. Since this PR now derives device, mount, and group policy from those specs, arbitrary CDI vendors can broaden sandbox permissions behind a GPU request. Please require nvidia.com/gpu= for explicit IDs, matching the default inventory filter, and add a negative unit test.

[elezar]

I don't agree that these should be NVIDIA-SPECIFIC. CDI is vendor agnostic, and we should be able to use the same mechanism to inject CDI devices from other vendors. I agree that we could check for valid CDI device IDs though.

[krishicks]

I looked at rebasing this and found two issues:

1. The PR as it stands doesn't properly compile on macOS because the new container-device-interface crate that's pulled in is Linux-only. I have a commit locally that fixes that so that it can build on macOS
2. The conflict from rebasing is substantial. I had an agent analyze the conflict without trying to resolve it, output in details below

Details

The conflict is understandable: main added OCI image identity and working-directory handling in the same code that PR #2265 changes for CDI. It is not safe to choose either side wholesale. There are four conflicted files, with the conflict originating in feat(gpu): derive sandbox policy from CDI specs and then propagating through the two descendant commits.

• crates/openshell-driver-docker/src/lib.rs:2275: main added build_environment_for_oci_user(..., oci_user) while CDI added include_cdi_context. The resolution needs both parameters. The test helper should preserve the CDI boolean while supplying an empty OCI user.

• crates/openshell-driver-docker/src/lib.rs:2631: main requires working_dir: "/" and passes image.user; CDI needs to pass whether GPU selection requested a CDI context. Both behaviors must be retained.

• crates/openshell-driver-docker/src/tests.rs:1476: mostly mechanical. Keep main’s renamed test and workspace assertion, but use the new GPU-aware runtime_config(false) signature.

• crates/openshell-supervisor-process/src/process.rs:2077: this is the substantive conflict. Main added distinct supplementary-group handling for OCI-derived identities, while CDI adds additionalGids. The combined result must merge CDI groups into both:

  • OCI image-user supplementary groups.
  • Explicit policy/named-user groups.

The supervisor merge deserves extra care because main now uses supplementary groups during workspace authorization, before privilege dropping. Ideally CDI groups should be incorporated into the common resolved identity so workspace validation and the eventual setgroups() call see the same group set. Simply pasting the old CDI block after main’s new logic could reject a valid workspace or overwrite OCI-derived groups.

Cargo.lock:1166 has four textual regions caused by main’s dependency updates colliding with CDI’s new packages. It should be regenerated from the merged manifests, retaining main’s newer dependency selections rather than selecting either lockfile side manually.

[drew]

The current bind-mount implementation is coherent, but the documented lifecycle still describes the abandoned archive-upload design, and the upload-only tar dependency remains in the production dependency graph.

[drew]

[P2] Update the documented CDI context lifecycle to match the implementation. The driver now writes a gateway-owned context file and bind-mounts it read-only during container creation; it no longer uploads an archive after create. This row and the prose below still promise a post-create upload and upload-failure cleanup. The same stale contract appears in architecture/compute-runtimes.md and docs/reference/sandbox-compute-drivers.mdx. Please update all three surfaces (and the PR description) to describe the bind-mounted lifecycle and its actual failure behavior.

[elezar]

Done.