docs(reference): clarify accelerator / Capacity Block / clique semantics

[resker]

Description

Refines the semantic description of three entries in `docs/reference/node-labels.md` to reflect the distinct underlying concepts — and the semantic mismatch that exists between topograph providers — with citation-backed language.

Surfaced in NVIDIA/NVSentinel#1205 while discussing how NVSentinel's Metadata Augmentor should treat Topograph's labels vs existing AWS NFD labels. Additional empirical data from an NVIDIA-internal cluster showed that multiple distinct `nvidia.com/gpu.clique` values can share the same `topology.k8s.aws/capacity-block-id`, and cliques can be absent when Fabric Manager initialization has not completed — invalidating the prior doc's implicit 1:1 framing.

Changes

1. `network.topology.nvidia.com/accelerator` description

The label was previously described as "NVLink domain (clique) ID". That's accurate for providers that derive their accelerator value from Fabric Manager (DRA, InfiniBand, Lambda AI), but not for the AWS provider, which derives its accelerator value from the AWS Capacity Block reservation ID (`pkg/providers/aws/instance_topology.go#L110-L111`) — a reservation-scoped identifier, not an NVLink-partition identifier.

New description names the label "Accelerated interconnect domain identifier" and flags that exact semantics are provider-dependent, pointing at the provider matrix below the table.

2. `topology.k8s.aws/capacity-block-id` description

Replaces the prior "AWS Capacity Block (NVLink domain)" framing. Per the AWS EC2 API reference for `InstanceTopology`, on UltraServer instances the field "identifies instances within the UltraServer domain" — a reservation-scoped grouping. On P6e-GB200 it is co-extensive with one UltraServer (AWS requires reserving the UltraServer as a unit per the EKS UltraServer guide), but AWS's explicit "same NVLink domain" label is `topology.k8s.aws/ultraserver-id`, not `capacity-block-id`. The finer-grained NVLink partition — potentially multiple per UltraServer — is surfaced by the NVIDIA GPU Operator as `nvidia.com/gpu.clique`.

3. `nvidia.com/gpu.clique` description

Adds the Fabric-Manager-completion precondition (`NVML_GPU_FABRIC_STATE_COMPLETED`), notes that the label can be absent on MNNVL nodes where Fabric Manager init has not completed, and clarifies that a clique is a logical sub-domain of an MNNVL — so multiple clique values can appear within a single NVLink domain (e.g., an x72 UltraServer split into two x36 halves).

Follow-up (not in this PR)

The semantic mismatch between topograph's AWS provider (writes reservation-scoped CapacityBlockId) and the other MNNVL-aware providers (write Fabric-Manager clique IDs) will be tracked as a separate design issue. Concrete options there include: (a) AWS provider prefers `topology.k8s.aws/ultraserver-id` (when present) or `nvidia.com/gpu.clique` (when Fabric Manager has completed) over `CapacityBlockId`; (b) `accelerator` is split into two labels with different granularity; (c) left as-is and the doc's provider-dependent note suffices. Out of scope here; this PR is doc-only.

Checklist

• Documentation Impact Evaluation — the changed section is `docs/reference/node-labels.md`; no other doc pages repeat these definitions authoritatively
• `make qualify` — N/A (docs-only)
• Every commit has a DCO sign-off

[greptile-apps]

Greptile Summary

This docs-only PR refines the semantic descriptions of three label entries in docs/reference/node-labels.md to accurately reflect provider-dependent granularity (accelerator carries an NVL Partition ID on MNNVL-aware providers but a reservation-scoped CapacityBlockId on AWS), adds Fabric Manager initialisation preconditions and a scheduler label-choice guide for nvidia.com/gpu.clique, and updates the NVSentinel integration section to reflect default allowedLabels inclusion. The k8s.md change is a one-line cross-reference clean-up.

Confidence Score: 5/5

Safe to merge — docs-only change with no runtime impact and two minor P2 style nits.

All findings are P2 (inconsistent NVML constant name, ephemeral release phrasing). The semantic content is well-sourced, the provider-dependency clarifications are accurate per the PR description and cited AWS API references, and no code paths are touched.

No files require special attention.

Important Files Changed

Filename	Overview
docs/reference/node-labels.md	Significantly expanded with provider-dependent accelerator semantics, Fabric Manager init preconditions, a scheduler label-choice guide, and richer nvidia.com/gpu.clique and capacity-block-id descriptions; two minor style inconsistencies (NVML constant name, ephemeral release phrasing).
docs/engines/k8s.md	Single-line change replacing an inline GPU_FABRIC_STATE_COMPLETED explanation with a cross-reference link to node-labels.md; the link has no anchor, but all content is still reachable at the top of that page.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Scheduler needs topology label] --> B{Kubernetes cluster?}
    B -- No --> C[Read Slurm topology.conf directly]
    B -- Yes --> D{MNNVL hardware?}
    D -- No --> E[Use network.topology.nvidia.com/accelerator\nInfiniBand provider only source]
    D -- Yes --> F{Fabric Manager init\ncompleted?\nNVML_GPU_FABRIC_STATE_COMPLETED}
    F -- No --> G[nvidia.com/gpu.clique absent\nUse network.topology.nvidia.com/accelerator]
    F -- Yes --> H{Which provider?}
    H -- AWS --> I{Granularity needed?}
    H -- DRA / InfiniBand / Lambda AI --> J[Both labels carry same value\nnvidia.com/gpu.clique or accelerator]
    I -- NVL Domain --> K[Use network.topology.nvidia.com/accelerator\nCapacityBlockId = NVL Domain]
    I -- NVL Partition --> L[Use nvidia.com/gpu.clique\nCliqueID = finer sub-domain]
    J --> M[Need switch-level locality?]
    K --> M
    L --> M
    E --> M
    G --> M
    M -- Yes --> N[Add leaf / spine / core labels\nfrom InfiniBand or NetQ provider]
    M -- No --> O[Done]
    N --> O

Loading

_{Reviews (5): Last reviewed commit: "docs(reference): clarify accelerator / C..." | Re-trigger Greptile}