feat(gpu): move device selection to driver config

[elezar]

Summary

Move exact GPU device selection out of the public sandbox proto/API and into driver-specific driver_config fields.

Related Issue

Related to #1716 and #1812.

Changes

• Remove public and driver proto gpu_device fields, reserving the field numbers and names.
• Remove the CLI --gpu-device flag.
• Add Docker/Podman exact GPU selection through driver_config.cdi_devices.
• Add VM exact GPU selection through driver_config.gpu_device_ids, currently limited to one entry.
• Require gpu=true when exact GPU device config is supplied, and reject exact selection for Kubernetes.
• Update GPU e2e coverage and user-facing docs for the new --driver-config-json path.

Testing

• mise run pre-commit passes
• Unit tests added/updated
• E2E tests added/updated

Checklist

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

[github-actions]

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

[github-actions]

Label test:e2e-gpu applied for 0df61f4. 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.

[elezar]

gator-agent

PR Review Status

Validation: this is maintainer-authored, project-valid GPU driver/API boundary work related to #1716 and #1812.
Head SHA: 253644cc5e662891772779bf696fccb01530179a

Review findings:

• Blocking: crates/openshell-driver-kubernetes/src/driver.rs still silently ignores unknown Kubernetes driver_config fields. That means {"kubernetes":{"cdi_devices":["nvidia.com/gpu=0"]}} or gpu_device_ids can launch as a generic --gpu Kubernetes sandbox instead of clearly rejecting exact GPU selection. This contradicts the PR contract and can expose a different GPU set than the user intended. Please explicitly reject Kubernetes exact-selection keys during create validation and add focused tests for both unsupported keys.
• Related reviewer note: alangou's latest review comment asks whether the GPU fallback should select one GPU. The current VM fallback preserves the previous omitted-device behavior, but the Kubernetes exact-selection rejection above still needs author disposition.

Docs: Fern docs were updated for the new --driver-config-json path.
Checks: current required checks, including OpenShell / GPU E2E, are green.
E2E: test:e2e-gpu is applied and the GPU E2E required gate is green.

Next state: gator:in-review

[elezar]

gator-agent

Re-check After Author Update

I re-evaluated latest head 253644cc5e662891772779bf696fccb01530179a after elezar's 2026-06-10 14:18 UTC review-thread response about the GPU fallback behavior.

Disposition: partially resolved.

Remaining items:

• The response resolves alangou's question by pointing the one-GPU fallback behavior to fix(gpu): select single CDI GPU defaults #1675.
• The blocking gator finding remains unresolved: Kubernetes driver_config exact-selection keys such as cdi_devices or gpu_device_ids still need to be explicitly rejected during create validation, with focused tests for the unsupported keys.

Next state: gator:in-review

[elezar]

gator-agent

Re-check After Author Update

I re-evaluated latest head b68e4403158ad2647c5ba9a4e53aaf227420985c after the new commit fix(kubernetes): reject unknown driver config fields.

Disposition: resolved.

Remaining items:

• No blocking review items remain. The Kubernetes driver now rejects unknown driver_config fields, validates the config before create, and includes focused tests for unsupported exact-selection keys such as cdi_devices.

Checks: required checks need to run again for the new head; test:e2e-gpu remains applied.

Next state: gator:watch-pipeline

[elezar]

gator-agent

Maintainer Approval Needed

Gator validation and PR monitoring are complete.

Validation: maintainer-authored GPU driver/API boundary work scoped to moving device selection into driver configuration.
Review: the prior blocking Kubernetes driver-config finding is resolved at head b68e4403158ad2647c5ba9a4e53aaf227420985c; no blocking review items remain.
Docs: Fern docs were updated for the new driver configuration path.
Checks: OpenShell / Branch Checks, OpenShell / Helm Lint, DCO, and OpenShell / GPU E2E are green for the current head.
E2E: test:e2e-gpu is applied and the GPU E2E required gate is green.

Human maintainer approval or merge decision is now required.

[elezar]

gator-agent

Blocked

Gator is blocked by merge conflicts: GitHub now reports mergeStateStatus=DIRTY for head b68e4403158ad2647c5ba9a4e53aaf227420985c, so this PR is no longer merge-ready despite the prior approval-needed handoff.

Next action: @elezar update the branch against current main and resolve the conflicts. After the branch is mergeable again, gator should re-check that the required gates are still green and then return this to maintainer approval if nothing else changed.

Next state: gator:blocked

[elezar]

gator-agent

Re-check After Author Update

I re-evaluated latest head 70acb90fbb45e435fcb1980510ea1c83dd7f9584 after the branch update that followed the prior merge-conflict blocker.

Disposition: resolved for the blocker. GitHub no longer reports mergeStateStatus=DIRTY; the remaining gates are pipeline and maintainer-review gates for the new head.

Remaining items:

• OpenShell / Branch Checks and OpenShell / GPU E2E are pending for the current head.
• test:e2e-gpu remains applied.

Next state: gator:watch-pipeline

[elezar]

gator-agent

Maintainer Approval Needed

Gator validation and PR monitoring are complete for the updated branch.

Validation: maintainer-authored GPU driver/API boundary work scoped to moving device selection into driver configuration.
Review: the prior blocking Kubernetes driver-config finding was resolved, and no blocking review items remain at head 70acb90fbb45e435fcb1980510ea1c83dd7f9584.
Docs: Fern docs were updated for the new driver configuration path.
Checks: OpenShell / Branch Checks, OpenShell / Helm Lint, DCO, and OpenShell / GPU E2E are green for the current head.
E2E: test:e2e-gpu is applied and the GPU E2E required gate is green.

Human maintainer approval or merge decision is now required.

[elezar]

gator-agent

Re-check After Maintainer Review

I re-evaluated latest head 70acb90fbb45e435fcb1980510ea1c83dd7f9584 after alangou's 2026-06-11 09:11 UTC approving review.

Disposition: approval received.

Remaining items:

• No blocking gator review items remain.
• OpenShell / Branch Checks, OpenShell / Helm Lint, DCO, and OpenShell / GPU E2E are green for the current head.
• Human maintainer merge decision remains.

Next state: gator:approval-needed