docs(reference): add authoritative node labels and annotations reference

[resker]

Summary

Adds docs/reference/node-labels.md — the authoritative reference for every label and annotation key written by Topograph, requested in #179.

Covers:

• The four default label keys (network.topology.nvidia.com/{accelerator,leaf,spine,core}) with topology type and semantics
• Per-provider matrix showing which providers emit accelerator (block) vs. leaf/spine/core (tree), including value format details (IB providers produce ClusterUUID.CliqueId; NetQ uses NMX DomainUUID)
• Relationship to nvidia.com/gpu.clique — on MNNVL systems the IB accelerator value matches; on non-MNNVL systems (B200/B300) gpu.clique is not set at all, making Topograph the only topology source
• FNV-64a hash truncation behavior for label values >63 chars
• Helm topologyNodeLabels configuration for customizing key prefixes
• "Without Topograph" reference — standard Kubernetes + cloud provider + GPU Operator labels that are available by default
• topograph.nvidia.com/ annotation keys (internal bookkeeping)
• NVSentinel integration pattern for topology-aware fault blast-radius analysis

Test plan

• Every label key verified against pkg/engines/k8s/labeler.go constants
• Provider matrix cross-checked against each provider's topology emission
• ClusterUUID.CliqueId format verified against pkg/providers/infiniband/common.go (nvidia-smi -q | grep "ClusterUUID\|CliqueId") and NVIDIA/k8s-device-plugin/internal/lm/imex.go
• DomainUUID format verified against pkg/providers/netq/nmx.go
• GPU_FABRIC_STATE_COMPLETED behavior verified against NVIDIA/go-nvlib/pkg/nvlib/device/device.go:IsFabricAttached()
• FNV-64a behavior verified against pkg/engines/k8s/labeler.go:checkLabel

Closes #179

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 68.46%. Comparing base (1875ab8) to head (4480ab4).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #254   +/-   ##
=======================================
  Coverage   68.46%   68.46%           
=======================================
  Files          82       82           
  Lines        4842     4842           
=======================================
  Hits         3315     3315           
  Misses       1395     1395           
  Partials      132      132           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[greptile-apps]

Greptile Summary

Adds docs/reference/node-labels.md as the authoritative reference for every label and annotation key written by Topograph (closes #179). All annotation key constants were verified against pkg/topology/topology.go, all four default label key constants were verified against pkg/engines/k8s/labeler.go, the FNV-64a hash truncation with x-prefix was confirmed from checkLabel(), the cw provider's incompatible vertex structure is now correctly documented, and the lambdai and netq block-value formats were cross-checked against their respective provider code.

Confidence Score: 5/5

Safe to merge — documentation only, all key facts verified against source code, one minor notation ambiguity that does not affect correctness.

All P0/P1 concerns from prior review rounds have been addressed: the x-prefixed FNV hash is now documented correctly, and cw/lambdai are now included in the matrix with accurate descriptions. The single remaining finding (lambdai value format notation) is a P2 style suggestion that does not affect functional correctness.

No files require special attention.

Important Files Changed

Filename	Overview
docs/reference/node-labels.md	New authoritative reference for all Topograph node labels and annotations; all annotation keys, label key constants, provider matrix entries, and hash-truncation behavior verified against source code — one minor notation ambiguity in the lambdai block value format.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    Provider["Provider\n(aws / gcp / oci / nebius / netq /\ninfiniband-bm / infiniband-k8s /\nlambdai / cw / dra)"]
    Provider -->|GenerateTopologyConfig| Root["Vertex root"]
    Root -->|topology/block| BlockRoot["Block root\n(optional)"]
    Root -->|topology/tree| TreeRoot["Tree root\n(optional)"]

    BlockRoot --> Block["Block vertex\n(NVLink domain / CapacityBlock)"]
    Block --> NodeB["Compute node"]

    TreeRoot --> Core["Core switch\n(optional)"]
    Core --> Spine["Spine switch\n(optional)"]
    Spine --> Leaf["Leaf switch"]
    Leaf --> NodeT["Compute node"]

    Block -->|checkLabel| AccLabel["network.topology.nvidia.com/accelerator"]
    Leaf -->|checkLabel| LeafLabel["network.topology.nvidia.com/leaf"]
    Spine -->|checkLabel| SpineLabel["network.topology.nvidia.com/spine"]
    Core -->|checkLabel| CoreLabel["network.topology.nvidia.com/core"]

    checkLabel{"len > 63?"}
    AccLabel --> checkLabel
    checkLabel -->|No| RawVal["raw value"]
    checkLabel -->|Yes| Hash["x-prefixed FNV-64a hex\ne.g. x3e4f1a2b3c4d5e6f"]

Loading

_{Reviews (4): Last reviewed commit: "docs(reference): fix broken engine links..." | Re-trigger Greptile}

[greptile-apps]

FNV-64a hash value includes an x prefix

The description says "hex-encoded," but checkLabel() in pkg/engines/k8s/labeler.go formats the value as fmt.Sprintf("x%x", h.Sum64()) — the resulting label value is a lowercase hex string with a leading x (e.g., x3e4f1a2b3c4d5e6f), not a bare hex string. Operators who grep for or compare label values need to know this prefix is present.

Suggested change

Label values are used as-is when they are 63 characters or shorter (the Kubernetes label value limit). Values longer than 63 characters are replaced with their **FNV-64a hash** (hex-encoded) to stay within the limit. This means two nodes with the same long switch identifier will carry the same hash value — locality is preserved, but the original identifier is not recoverable from the label alone.

Label values are used as-is when they are 63 characters or shorter (the Kubernetes label value limit). Values longer than 63 characters are replaced with their **FNV-64a hash** (formatted as `x` followed by lowercase hex, e.g., `x3e4f1a2b3c4d5e6f`) to stay within the limit. This means two nodes with the same long switch identifier will carry the same hash value — locality is preserved, but the original identifier is not recoverable from the label alone.

[greptile-apps]

Provider matrix omits lambdai and cw

Two registered providers are absent from the matrix even though both write topology labels. lambdai (pkg/providers/lambdai/instance_topology.go) sets AcceleratorID = NVLink.DomainID + "." + NVLink.CliqueID and passes it through ToThreeTierGraph, so it emits both block (accelerator) and tree (leaf/spine/core) labels. cw (pkg/providers/cw/provider.go) calls ib.GenerateTopologyConfig and wraps the output as a bare tree root (no toGraph() call), so it emits tree-only labels.

Suggested additions to the matrix:

Suggested change

	|---|---|---|
	| `aws` | Yes (CapacityBlockId) | Yes |
	| `gcp` | No | Yes |
	| `oci` | No | Yes |
	| `nebius` | No | Yes |
	| `netq` | Yes (NMX `DomainUUID`) | Yes (Spectrum-X switch hierarchy) |
	| `dra` | Yes (reads `nvidia.com/gpu.clique`) | No |
	| `infiniband-bm` | Yes (`ClusterUUID.CliqueId`) | Yes (IB switch hierarchy) |
	| `infiniband-k8s` | Yes (`ClusterUUID.CliqueId`) | Yes (IB switch hierarchy) |
	| `aws` | Yes (CapacityBlockId) | Yes |
	| `cw` | No | Yes (IB switch hierarchy) |
	| `gcp` | No | Yes |
	| `lambdai` | Yes (`NVLink.DomainID.CliqueID`) | Yes |
	| `oci` | No | Yes |
	| `nebius` | No | Yes |
	| `netq` | Yes (NMX `DomainUUID`) | Yes (Spectrum-X switch hierarchy) |
	| `dra` | Yes (reads `nvidia.com/gpu.clique`) | No |
	| `infiniband-bm` | Yes (`ClusterUUID.CliqueId`) | Yes (IB switch hierarchy) |
	| `infiniband-k8s` | Yes (`ClusterUUID.CliqueId`) | Yes (IB switch hierarchy) |

[greptile-apps]

cw tree column is incorrect — no labels are emitted

cw.GenerateTopologyConfig returns a raw treeRoot vertex where children are keyed by switch IDs, not wrapped under the "topology/tree" key. Both the k8s labeler (ApplyNodeLabels, labeler.go:77) and the Slinky engine's initTree (translate/topology.go:118) gate all tree processing on root.Vertices[topology.TopologyTree] — a key that is never present in the cw output. As a result, the cw provider produces no node labels at all through either engine.

Compare cw's return value:

// cw/provider.go — switch IDs as keys, no "topology/tree" wrapper
treeRoot := &topology.Vertex{Vertices: make(map[string]*topology.Vertex)}
for _, v := range roots {
    treeRoot.Vertices[v.ID] = v  // keys are switch identifiers
}
return treeRoot, nil

With netq's correct structure:

// netq/provider.go — properly wrapped
root.Vertices[topology.TopologyTree] = treeRoot

The tree column for cw should be "No" until the provider is updated to wrap its output, or the code should be fixed and the doc updated to "Yes" once the provider emits the expected structure.

Suggested change

	| `cw` | No | Yes (IB switch hierarchy) |
	| `cw` | No | No (vertex structure incompatible with labeler — see pkg/providers/cw/provider.go) |