# GPU workload images This directory defines workload test images for OpenShell GPU validation. ## Contract Each workload image must: - Use the standard OpenShell sandbox base image as its final-stage base or ensure that the requirements for a sandbox image are met. - Provide a manifest command that runs the workload inside the sandbox image. - Run the same workload as the image default entrypoint for direct container-engine validation. - Require no network access after the image is pulled. - Print `OPENSHELL_GPU_WORKLOAD_SUCCESS` only when validation succeeds. - Print `OPENSHELL_GPU_WORKLOAD_FAILURE` and exit non-zero when validation fails. - Be usable as an OpenShell sandbox image when OpenShell invokes the manifest command explicitly. OpenShell sandbox creation replaces the image entrypoint with the supervisor and does not run the OCI image `CMD`. When these images are used through OpenShell, the workload command from each manifest entry must be passed explicitly. The image build task writes a local workload manifest. Each workload entry carries: - `name` - `image` - `command` - `expect` - `requirements` ## Images | Source directory | Image name | Purpose | | --- | --- | --- | | `smoke-pass` | `gpu-workload-smoke-pass` | Always succeeds and prints the success marker. | | `smoke-fail` | `gpu-workload-smoke-fail` | Always fails and prints the failure marker. | | `cuda-basic` | `gpu-workload-cuda-basic` | Runs CUDA `deviceQuery` and `vectorAdd` validation. | ## Build Build all workload images: ```shell mise run e2e:workloads:build ``` Build a subset by source directory name: ```shell OPENSHELL_GPU_WORKLOAD_IMAGES=smoke-pass,smoke-fail \ mise run e2e:workloads:build ``` The build task uses `tasks/scripts/container-engine.sh`. Set `CONTAINER_ENGINE=docker` or `CONTAINER_ENGINE=podman` to choose an engine explicitly. When unset, the helper uses its existing auto-detection behavior. Local tags use the current commit short SHA plus a short fingerprint of the external build inputs. Dirty local trees append `-dirty`. Set `OPENSHELL_GPU_WORKLOAD_IMAGE_TAG=` to override the tag. The task writes the latest build refs to: ```text e2e/gpu/images/.build/latest.env ``` The task also writes a local workload manifest for downstream tooling and future workload-runner integration: ```text e2e/gpu/images/.build/workloads.yaml ``` That local manifest is created by `mise run e2e:workloads:build`. It contains the full image reference, command, expected outcome, and requirements for each selected workload. It also records the external build inputs used to produce the workload images. Use the env file in later commands: ```shell source e2e/gpu/images/.build/latest.env ``` That env file exports `OPENSHELL_E2E_WORKLOAD_MANIFEST` pointing at the local manifest. The current checked-in Rust GPU e2e target does not consume this manifest yet. The per-image refs remain available as a convenience for direct container-engine validation. ## Direct Validation Validate smoke pass: ```shell docker run --rm "${OPENSHELL_E2E_GPU_SMOKE_PASS_IMAGE}" ``` Validate smoke fail: ```shell docker run --rm "${OPENSHELL_E2E_GPU_SMOKE_FAIL_IMAGE}" ``` The smoke fail command should exit non-zero and print `OPENSHELL_GPU_WORKLOAD_FAILURE`. Validate CUDA with Docker CDI: ```shell docker run --rm --device nvidia.com/gpu=all \ "${OPENSHELL_E2E_GPU_CUDA_WORKLOAD_IMAGE}" ``` Use `podman run` with the same `--device nvidia.com/gpu=all` option on hosts where Podman CDI is configured. Direct container-engine validation catches image, CDI, CUDA, and host GPU setup issues before OpenShell sandbox behavior is involved. ## OpenShell GPU E2E The current Rust GPU validation target is: ```shell mise run e2e:gpu ``` That target runs `gpu_device_selection`. It validates GPU request and device selection behavior against a Docker-backed gateway. It does not run the workload manifest generated by `mise run e2e:workloads:build`.