Topology Presets¶
Topology presets describe known server layouts by machine type, GPU type, PF PCI address, traffic direction, rail, NUMA node, and GPU proximity.
How Presets Are Used¶
| Flow | Behavior |
|---|---|
| Discovery overlay | l8k discover matches a preset by exact (machineType, gpuType), validates PF count, PCI addresses, and device IDs, and applies topology fields only when the hardware matches exactly. |
| Offline generation | l8k generate --for <preset> replaces render topology in clusterConfig and renders manifests without cluster access. Existing host observations retain their discovery membership. |
Presets are all-or-nothing. When a matched preset deviates from live hardware, l8k records the deviation and keeps live-discovered topology instead of partially overlaying stale rail data.
List Presets¶
Bundled presets include:
GB200-NVL-NVIDIA-GB200GB300-DGX-Station-NVIDIA-GB300GB300-NVL-NVIDIA-GB300PowerEdge-R760xa-H100-NVLPowerEdge-XE7745-RTX-PRO-4500PowerEdge-XE9680-H200ThinkSystem-SR650-V4-RTX-PRO-6000ThinkSystem-SR675-V3-H200-NVLThinkSystem-SR675-V3-RTX-PRO-6000ThinkSystem-SR675-V3-System-Board-RTX-PRO-6000ThinkSystem-SR680a-V3-H200UCSC-885A-M8-H22-H200
The GB200-NVL-NVIDIA-GB200 preset describes the four-rail ConnectX-7
InfiniBand tray reported in issue #323.
It preserves the discovered GPU0–GPU3 associations and SYS proximity, with
rails 0–1 on NUMA 0 and rails 2–3 on NUMA 1. It also includes the two north-south
BlueField-3s at 0006:03:00.0 and 0016:03:00.0, without rail assignments.
When those BlueFields are host-restricted, discovery excludes them; the resulting
four-PF inventory reports a topology deviation from this six-PF preset.
Update Presets¶
Download a catalog from a Git repository into the active filesystem override:
Select the source or destination explicitly:
l8k preset update \
--repo nvidia/k8s-launch-kit \
--branch main
l8k preset update \
--dir /etc/l8k/presets
Use --config-dir /etc/l8k on later commands to select a catalog stored under /etc/l8k/presets.
Generate From A Preset¶
l8k generate \
--for PowerEdge-XE9680-H200 \
--node-selector "nvidia.com/gpu.product=NVIDIA-H200" \
--fabric ethernet \
--deployment-type sriov \
--save-deployment-files ./deployment
--node-selector is required because the synthesized cluster config has no live worker-node list.
Presets apply only to topology. When --user-config includes discovery-time
DOCA-HOST observations, the original discovery workers still determine driver
ownership and release compatibility. All-installed evidence can disable the
container driver; mixed evidence requires an explicit choice, and a release
mismatch still warns during generation and fails later validation. Explicit
driver choices retain precedence. Preset-only input without host observations
keeps the container-driver default of true.
Generation preserves the host observation membership separately in
discoveredDocaHostScope in .l8k/resolved-config.yaml. It does not copy worker
names or host package state into preset topology. Reusing that configuration,
with or without --for, retains the same host checks. See
host discovery for snapshot lifetime.
Preset YAML¶
machineType: PowerEdge-XE9680
gpuType: NVIDIA-H200
manufacturer: Dell
nicModel: BlueField-3 SuperNIC
capabilities:
nodes:
sriov: true
rdma: true
ib: false
pfs:
- deviceID: a2dc
pciAddress: 0000:1a:00.0
rdmaDevice: rocep26s0f0
networkInterface: eth2
traffic: east-west
rail: 0
numaNode: 0
connectedGPU: GPU0
gpuProximity: PIX
The capabilities.nodes block is required for --for because profile selection happens
without live discovery. If you select InfiniBand with --fabric infiniband, set
capabilities.nodes.ib: true; profile selection rejects the request when that capability is
false or omitted.
Author A Preset¶
- Collect topology on a representative node for the exact machine/GPU pair. Record every PF, including north-south interfaces, and confirm its PCI address, device ID, traffic role, rail, NUMA node, and GPU association.
- Set
machineTypeto the existingnvidia.com/gpu.machinelabel, or the discovered/sys/class/dmi/id/product_namevalue with spaces normalized to dashes. SetgpuTypetonvidia.com/gpu.productor the sanitized GPU product name from discovery. Copy the persisted values fromcluster-config.yamlwhen available; matching is exact and case-sensitive. - Create
presets/<unique-machine-gpu-variant>/topology.yaml. Include both matching keys andcapabilities.nodesfor offline--foruse. Keep rail assignments andconnectedGPU: GPU<N>consistent with the physical layout; do not infer a missing association as GPU0. - Put the candidate under a dedicated config directory and test it locally:
l8k preset list --config-dir ./preset-review
l8k generate --config-dir ./preset-review \
--for MyServer-H200 --node-selector rack=42 \
--fabric ethernet --deployment-type sriov \
--save-deployment-files ./preset-review-output --output json
These examples expect preset-review/presets/MyServer-H200/topology.yaml.
The override replaces the catalog, so include every preset needed for the
review. Inspect networks, resource names, selectors, and GPU requests in
the rendered output. Rendering does not certify the hardware.
5. Compare the complete PF inventory with discovery from the target hardware
and resolve any preset deviations before using the preset for deployment.
Validation And Deviations¶
Preset lookup is an exact match on (machineType, gpuType). After lookup, Launch Kit compares:
- PF count.
- The complete PCI-address set.
- Device ID at every shared PCI address.
Part number and PSID differences are not topology deviations because firmware and SKU variants are expected.
When the topology differs, discovery:
- Records each difference under
clusterConfig[].presetDeviation. - Keeps the live-discovered traffic, rail, NUMA, and GPU-affinity data.
- Does not partially apply the preset.
- Repeats the warning whenever the config is loaded.
presetDeviation:
- field: pfCount
expected: "8"
got: "6"
detail: PF count differs from preset
- field: deviceID
expected: 1023@0000:5e:00.0
got: a2dc@0000:5e:00.0
detail: device ID at PCI address differs from preset
l8k validate compares the saved group with the current catalog again. A topology mismatch appears as paired actual/expected hardware in the report and prevents the deployment from receiving a green-light result.
Override The Catalog¶
Use --config-dir to replace the embedded catalog:
l8k preset list --config-dir /etc/l8k
l8k generate --config-dir /etc/l8k --for MyServer-H200 --node-selector rack=42
The override directory must contain presets/<name>/topology.yaml.