Cluster Topology Presets

On this page

Note

Use this when: you want to generate manifests without running discovery against a live cluster — for offline manifest generation, CI pipelines, or known machine types where the topology is fixed.

A preset is a pre-recorded hardware topology for a known machine type (e.g., ThinkSystem-SR680a-V3, PowerEdge-XE9680). Each preset records expected PCI addresses, traffic class, NUMA affinity, and rail assignments for a specific machine + GPU pairing.

Launch Kit uses presets in two ways:

  • Discovery overlay — when discovery detects an exact matching machine and GPU type, the preset’s topology is overlaid for consistency.

  • Offline generation — l8k generate --for <preset> skips discovery entirely.

Listing Presets

l8k preset list

Lists every preset known to the local installation.

Updating Presets

Download the latest presets from a Git repository:

l8k preset update

Optional flags:

  • --repo <owner/repo> — override the GitHub repository (default nvidia/k8s-launch-kit).

  • --branch <name> — fetch from a specific branch or tag.

  • --dir <path> — local destination directory for downloaded presets.

Discovery works without a matching preset. --for requires a preset present in the selected catalog; use the exact name from l8k preset list. Presets are embedded by default; --config-dir selects an override catalog.

Offline Manifest Generation

Generate manifests for a known preset without cluster access:

l8k generate --for ThinkSystem-SR680a-V3-H200 \
    --node-selector "nvidia.com/gpu.product=NVIDIA-H200" \
    --fabric ethernet --deployment-type sriov --multirail \
    --save-deployment-files ./deployments

The generated manifests will target nodes matching the supplied selector when applied. This is the recommended path for CI pipelines that produce deployment artefacts ahead of cluster availability.

Discovery Overlay

When l8k discover detects a machine type that matches a known preset, the preset’s PCI topology, NUMA affinity, and rail assignments are overlaid on the discovery output. This ensures consistent rail numbering and PCI ordering across discovery runs.

If no preset matches, discovery proceeds with the values it derives directly from hardware — see Discover Workflow.

Validation and Deviations

When a matched preset’s PFs don’t exactly match the discovered hardware, Launch Kit records the deviations instead of refusing to apply the preset. Discovery retains the discrepancy so it can be reviewed before deployment:

  • PF count mismatch — the preset and the cluster expose different numbers of PFs.

  • PCI address drift — a PCI address present in the preset is missing on the cluster, or vice versa.

  • Device-ID drift — the device ID at a matching PCI address differs from the preset.

Whenever any of these is detected, the matched preset is still applied on a best-effort basis (so rail/NUMA/GPU-affinity fields populate for whichever PFs do line up), and the discrepancies are written to ClusterConfig.presetDeviation in cluster-config.yaml. Whenever a config with non-empty presetDeviation is loaded by any l8k subcommand, a warning is re-emitted listing each deviation. Generation can proceed, but certified-preset deviations fail l8k validate with exit code 4. Resolve the mismatch or use an appropriate reviewed topology; a completed render does not qualify the hardware.

Part numbers and PSIDs are not strict criteria (firmware variants are expected) so they’re not checked.

Example presetDeviation block in cluster-config.yaml:

clusterConfig:
- identifier: "group-0"
  machineType: "PowerEdge-XE9680"
  gpuType: "NVIDIA-H200"
  presetDeviation:
  - field: pfCount
    expected: "10"
    got: "9"
    detail: "PF count differs from preset"
  - field: pciAddress
    got: "0000:bd:00.0"
    detail: "discovered PCI address not present in preset"
  - field: deviceID
    expected: "a2dc@0000:5e:00.0"
    got: "1023@0000:5e:00.0"
    detail: "device ID at PCI address differs from preset"

See Also