fix(kubernetes): reject explicit gpu devices

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

Author: elezar

architecture/compute-runtimes.md

@@ -84,7 +84,8 @@ dependencies, but they should not need to include the gateway. GPU-capable
 images must include the user-space libraries required by the workload. The
 runtime still owns GPU device injection. GPU requests can include a driver-native
 device identifier or a requested count; the gateway validates the request shape
-and each runtime enforces the GPU allocation modes it supports.
+and each runtime enforces the GPU allocation modes it supports. Kubernetes uses
+counted `nvidia.com/gpu` resources and rejects driver-native device identifiers.
 
 ## Deployment Shape
 

crates/openshell-driver-kubernetes/README.md

@@ -64,7 +64,9 @@ the supervisor's network namespace mount setup on AppArmor-enabled nodes.
 When a sandbox requests GPU support, the driver checks node allocatable capacity
 for `nvidia.com/gpu` and requests the configured GPU count in the workload spec.
 When no count is set, the driver requests one GPU resource. The sandbox image
-must provide the user-space libraries needed by the agent workload.
+must provide the user-space libraries needed by the agent workload. The driver
+does not support explicit GPU device identifiers; use the public `gpu` flag or
+`gpu_count`.
 
 ## Driver Config POC
 

crates/openshell-driver-kubernetes/src/driver.rs

@@ -173,6 +173,20 @@ impl std::fmt::Debug for KubernetesComputeDriver {
     }
 }
 
+fn gpu_request_validation_error(sandbox: &Sandbox) -> Option<&'static str> {
+    if sandbox
+        .spec
+        .as_ref()
+        .is_some_and(|spec| !spec.gpu_device.is_empty())
+    {
+        return Some(
+            "gpu_device is not supported by the kubernetes compute driver; use gpu or gpu_count",
+        );
+    }
+
+    None
+}
+
 impl KubernetesComputeDriver {
     pub async fn new(config: KubernetesComputeConfig) -> Result<Self, KubeError> {
         let base_config = match kube::Config::incluster() {
@@ -245,6 +259,10 @@ impl KubernetesComputeDriver {
     }
 
     pub async fn validate_sandbox_create(&self, sandbox: &Sandbox) -> Result<(), tonic::Status> {
+        if let Some(message) = gpu_request_validation_error(sandbox) {
+            return Err(tonic::Status::invalid_argument(message));
+        }
+
         let gpu_requested = sandbox.spec.as_ref().is_some_and(|spec| spec.gpu);
         if gpu_requested
             && !self.has_gpu_capacity().await.map_err(|err| {
@@ -2288,6 +2306,39 @@ mod tests {
         );
     }
 
+    #[test]
+    fn gpu_request_validation_error_rejects_gpu_device() {
+        let sandbox = Sandbox {
+            spec: Some(SandboxSpec {
+                gpu: true,
+                gpu_device: "nvidia.com/gpu=0".to_string(),
+                ..Default::default()
+            }),
+            ..Default::default()
+        };
+
+        assert_eq!(
+            gpu_request_validation_error(&sandbox),
+            Some(
+                "gpu_device is not supported by the kubernetes compute driver; use gpu or gpu_count"
+            )
+        );
+    }
+
+    #[test]
+    fn gpu_request_validation_error_accepts_gpu_count() {
+        let sandbox = Sandbox {
+            spec: Some(SandboxSpec {
+                gpu: true,
+                gpu_count: Some(2),
+                ..Default::default()
+            }),
+            ..Default::default()
+        };
+
+        assert_eq!(gpu_request_validation_error(&sandbox), None);
+    }
+
     #[test]
     fn gpu_sandbox_uses_template_runtime_class_name_when_set() {
         let template = SandboxTemplate {

docs/sandboxes/manage-sandboxes.mdx

@@ -84,10 +84,10 @@ openshell sandbox create --gpu-device nvidia.com/gpu=0 -- claude
 ```
 
 Support for count and device selection is driver-dependent. Kubernetes honors
-`--gpu-count` by setting the `nvidia.com/gpu` limit. Docker and Podman support
-explicit CDI device IDs through `--gpu-device` but reject count-based selection.
-VM gateways accept only one GPU, either through `--gpu`, `--gpu-count 1`, or
-`--gpu-device`.
+`--gpu-count` by setting the `nvidia.com/gpu` limit and rejects
+`--gpu-device`. Docker and Podman support explicit CDI device IDs through
+`--gpu-device` but reject count-based selection. VM gateways accept only one
+GPU, either through `--gpu`, `--gpu-count 1`, or `--gpu-device`.
 
 For Docker-backed sandboxes, GPU injection uses Docker CDI. If you enable Docker
 CDI after the gateway starts, restart the gateway so OpenShell can detect the