Skip to navigation
Getting Started

WorkloadRun Quick Start

View as Markdown

WorkloadRun is a simplified API for running a single workload against a set of nodes. It is useful for one-off benchmarks, smoke tests, and validating specific node groups without running the full certification suite.

When to use WorkloadRun vs Certification: Use WorkloadRun when you want to run a single workload — for example, a quick NCCL bandwidth check or a training smoke test — against a specific set of nodes. Use Certification when you need a full burn-in suite across all categories and node groups, with per-node pass/fail results and a structured report.

Before you begin

Install nvcrectl and set up the cluster before continuing.

Define a WorkloadRun

apiVersion: nvcre.nvidia.com/v1alpha1
kind: WorkloadRun
metadata:
  name: nccl-all-reduce
spec:
  image: nvcr.io/nvidia/pytorch:26.01-py3
  framework:
    mpi:
      binary: /usr/local/bin/all_reduce_perf_mpi
      args: ["-b", "8", "-e", "32G", "-f", "2", "-n", "100"]
      mpirunPath: /usr/local/mpi/bin/mpirun
  numNodes: 4
  orchestration:
    placement: Unpinned
  bandwidthMeasurement:
    logProfileRef: nccl-bandwidth
    testType: all_reduce

placement: Unpinned is what makes this a single four-node job. Without it, numNodes is a group size rather than a total: NVCRE partitions every node matching the target into groups of four and runs one job per group, so a 20-node cluster runs five jobs at once. Leave it out when you want that fleet-wide sweep, and see Placement for the full contract.

Run it

nvcrectl workloadrun run \
  --workload-registry nvcr.io \
  --workload-registry-username '$oauthtoken' \
  --workload-registry-password "$NGC_API_KEY" \
  --wait \
  nccl-all-reduce.yaml

nvcrectl auto-detects the platform and GPU architecture from the cluster’s node labels, applies the appropriate overrides, and streams log output until the workload completes.

View results

nvcrectl workloadrun report nccl-all-reduce

For workloads with bandwidthMeasurement configured, the report includes per-bus bandwidth results parsed from the NCCL output.

Next steps