OpenShell/e2e/gpu

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:

mise run e2e:workloads:build

Build a subset by source directory name:

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=<tag> to override the tag.

The task writes the latest build refs to:

e2e/gpu/images/.build/latest.env

The task also writes a local workload manifest for downstream tooling and future workload-runner integration:

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:

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:

docker run --rm "${OPENSHELL_E2E_GPU_SMOKE_PASS_IMAGE}"

Validate smoke fail:

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:

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:

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.