Run an image workload

The local hw-runner client can execute an existing OCI or Docker image without a GitLab CI pipeline. The image is pulled by Podman on the selected runner; RealHW does not build a Dockerfile or accept a build context in this workflow.

The web app currently manages GitLab project runners and interactive hardware leases. It does not yet submit this deployment file as a remote workload.

Local client command

Use a normalized deployment file with the runner CLI:

cargo run -p hw-runner -- run-deployment \
  examples/client-smoke.yaml \
  --output-dir /tmp/realhw-client-smoke

The current client path accepts one service and one replica. It reserves the requested CPU and memory, starts the image with Podman, forwards its logs, and returns the container exit code.

Collect artifacts

The output directory is mounted into the container at /out. Declare required files or globs in the service definition:

name: qemu-test
services:
  qemu:
    image: ghcr.io/acme/qemu-runner@sha256:...
    command: ["/usr/local/bin/run-tests"]
    resources:
      cpu_count: 4
      memory_bytes: 4294967296
    artifacts:
      - path: /out/**/*.log
        name: logs
        required: true
      - path: /out/results/**
        name: results

After the process exits, the runner prints each matching artifact. A required artifact that is missing makes the client command fail.

Request KVM

QEMU workloads request capabilities and an allowlisted device explicitly:

hardware:
  requires: ["arch:x86_64", "kvm", "vmx"]
  devices: [kvm]

The runner exposes /dev/kvm only when inventory and admission confirm that it is available. A GCE VM can provide this when nested virtualization and the guest device configuration are enabled; an ordinary SaaS Docker runner does not provide it.

Cloud-init and multi-service deployments

cloud_init is guest-only configuration for a VM-backed workload. It is not a host startup script and is not applied to an ordinary container. The local one-shot client rejects cloud-init, multiple services, and replicas. Remote submission for those deployment features is planned and is not part of the current web app.

On macOS, choose an output directory shared with the Podman machine, such as a path under the checked-out repository.