This issue is intended to discuss and align Topograph's direction - and highlight areas where contributions are especially desired!
Direction
Topograph's strategic positioning is to be the standard topology-discovery layer for AI cluster scheduling — a unified substrate that abstracts over diverse infrastructure sources (cloud APIs, InfiniBand fabric, NVIDIA-managed NVLink/Ethernet) and translates topology into the formats each scheduler can consume (Slurm topology.conf, Kubernetes node labels, Slinky ConfigMaps). The broader the provider and engine coverage, the more useful the standardized topology layer becomes for downstream schedulers (KAI Scheduler, Kueue, Grove, native pod affinity), operational tooling (NVSentinel), and the ecosystem of observability / placement tools that depend on accurate, real-time topology data.
We actively welcome community contribution. The provider interface is well-defined, the engine boundary is stable, and the project is designed to accept new integrations without touching shared internals.
Focus Areas
1. Additional cloud and colocation providers
If your infrastructure isn't covered by the existing AWS, GCP, OCI, Nebius, Lambda AI, and CoreWeave providers, adding support means integrating with your provider's topology API and implementing a new Topograph provider.
2. On-premises network fabrics
Expanding on-premises coverage requires collaboration with network switch vendors and operators. If you run InfiniBand, Ethernet, or other high-performance fabrics on-premises and have ideas about how node-to-switch relationships should be exposed reliably in your environment, please comment on this issue or open a new one describing the mechanism.
3. Kubernetes Workload API and KEP-5732
The Workload API brought gang scheduling into the core scheduler (alpha in Kubernetes 1.35). KEP-5732 extends it with a TopologyConstraint on PodGroupSpec — a node label key ensuring all pods in a gang land in the same topology domain — with DRA integration planned to follow. KEP-5732 is advancing on the standard track: alpha landed in v1.36 and beta targets v1.37 (sig-scheduling; WG workload-aware-scheduling). Because its TopologyConstraint keys off a node label, the labels Topograph's k8s engine applies are the natural input — which keeps label-based output strategically central as the feature matures.
4. Topology label standardization (KEP-4962) — stalled; NFD as the successor path
KEP-4962 proposed a standard network.topology.kubernetes.io/ label schema closely mirroring Topograph's network.topology.nvidia.com/ design, but it stalled in sig-network and was closed (not_planned) in May 2026 without landing (no merged KEP, code, or docs). The live direction for standardized topology publication has shifted toward Node Feature Discovery (see §7). Note the trade-off with §3: the advancing consumer (KEP-5732) keys off node labels, so Topograph's label output remains the primary scheduler-integration surface even as NFD-based publication is explored.
5. Grove ClusterTopology integration
The Grove project's roadmap includes automatic topology detection — generating ClusterTopology resources directly from the cluster's physical layout. Topograph is the natural source for that data. A native integration between Topograph and Grove's ClusterTopology API would close the loop between topology discovery and scheduling configuration automatically.
6. AICR integration
NVIDIA/aicr is a sibling project that curates AI-cluster configuration recipes. Adding Topograph as a first-class AICR recipe component (alongside KAI Scheduler and the DRA driver) would let AICR-managed clusters pick up topology labels out of the box. This is a cross-repo change that would land on the AICR side.
7. Node Feature Discovery (NFD) integration
With the KEP-4962 label-standardization effort stalled (§4), Node Feature Discovery has emerged as a successor path for publishing topology through a standard API. Two upstream proposals frame it: node-feature-discovery#2549 adds an nfd-network-topology-updater — publishing per-node NodeFeature attributes (accelerator/leaf/spine/core) and a NodeFeatureGroup per topology domain — and proposes Topograph as the initial code base, since it already discovers and maintains this topology. node-feature-discovery#2548 adds nested NodeFeatureGroups (containsGroups), letting the switch hierarchy (leaf ⊂ spine ⊂ core) be expressed by reference instead of duplicating node lists — important for etcd object-size limits at scale. The Topograph-side design is drafted in the nfd engine SDD (#382).
An open design question runs through this: NodeFeatureGroup exposes precomputed groups, so a scheduler must choose among them, whereas the label model (and KEP-5732's label-keyed TopologyConstraint, §3) compares values natively. Contributions that advance the NFD proposals, the nfd engine, and this labels-vs-groups trade-off help determine how topology awareness is consumed across the ecosystem.
How to engage
- Comment on this issue with questions, offers to pick up an area, or new focus-area proposals
- Open a new issue for a specific feature, bug, or integration; link back here if it maps to one of the focus areas above
- Submit a pull request — see
CONTRIBUTING.md for mechanics (DCO sign-off, conventional commits, pre-push checks) and AGENTS.md for structural conventions
Maintainer note
This issue is intended to be pinned to the repository's issue tracker for discoverability. Please maintain it as the authoritative list of direction-setting focus areas; update it as items are completed, added, or reframed.
This issue is intended to discuss and align Topograph's direction - and highlight areas where contributions are especially desired!
Direction
Topograph's strategic positioning is to be the standard topology-discovery layer for AI cluster scheduling — a unified substrate that abstracts over diverse infrastructure sources (cloud APIs, InfiniBand fabric, NVIDIA-managed NVLink/Ethernet) and translates topology into the formats each scheduler can consume (Slurm
topology.conf, Kubernetes node labels, Slinky ConfigMaps). The broader the provider and engine coverage, the more useful the standardized topology layer becomes for downstream schedulers (KAI Scheduler, Kueue, Grove, native pod affinity), operational tooling (NVSentinel), and the ecosystem of observability / placement tools that depend on accurate, real-time topology data.We actively welcome community contribution. The provider interface is well-defined, the engine boundary is stable, and the project is designed to accept new integrations without touching shared internals.
Focus Areas
1. Additional cloud and colocation providers
If your infrastructure isn't covered by the existing AWS, GCP, OCI, Nebius, Lambda AI, and CoreWeave providers, adding support means integrating with your provider's topology API and implementing a new Topograph provider.
AGENTS.mdpkg/providers/lambdai/,pkg/providers/cw/2. On-premises network fabrics
Expanding on-premises coverage requires collaboration with network switch vendors and operators. If you run InfiniBand, Ethernet, or other high-performance fabrics on-premises and have ideas about how node-to-switch relationships should be exposed reliably in your environment, please comment on this issue or open a new one describing the mechanism.
3. Kubernetes Workload API and KEP-5732
The Workload API brought gang scheduling into the core scheduler (alpha in Kubernetes 1.35). KEP-5732 extends it with a
TopologyConstraintonPodGroupSpec— a node label key ensuring all pods in a gang land in the same topology domain — with DRA integration planned to follow. KEP-5732 is advancing on the standard track: alpha landed in v1.36 and beta targets v1.37 (sig-scheduling; WG workload-aware-scheduling). Because itsTopologyConstraintkeys off a node label, the labels Topograph'sk8sengine applies are the natural input — which keeps label-based output strategically central as the feature matures.4. Topology label standardization (KEP-4962) — stalled; NFD as the successor path
KEP-4962 proposed a standard
network.topology.kubernetes.io/label schema closely mirroring Topograph'snetwork.topology.nvidia.com/design, but it stalled in sig-network and was closed (not_planned) in May 2026 without landing (no merged KEP, code, or docs). The live direction for standardized topology publication has shifted toward Node Feature Discovery (see §7). Note the trade-off with §3: the advancing consumer (KEP-5732) keys off node labels, so Topograph's label output remains the primary scheduler-integration surface even as NFD-based publication is explored.5. Grove
ClusterTopologyintegrationThe Grove project's roadmap includes automatic topology detection — generating
ClusterTopologyresources directly from the cluster's physical layout. Topograph is the natural source for that data. A native integration between Topograph and Grove'sClusterTopologyAPI would close the loop between topology discovery and scheduling configuration automatically.6. AICR integration
NVIDIA/aicr is a sibling project that curates AI-cluster configuration recipes. Adding Topograph as a first-class AICR recipe component (alongside KAI Scheduler and the DRA driver) would let AICR-managed clusters pick up topology labels out of the box. This is a cross-repo change that would land on the AICR side.
7. Node Feature Discovery (NFD) integration
With the KEP-4962 label-standardization effort stalled (§4), Node Feature Discovery has emerged as a successor path for publishing topology through a standard API. Two upstream proposals frame it: node-feature-discovery#2549 adds an
nfd-network-topology-updater— publishing per-nodeNodeFeatureattributes (accelerator/leaf/spine/core) and aNodeFeatureGroupper topology domain — and proposes Topograph as the initial code base, since it already discovers and maintains this topology. node-feature-discovery#2548 adds nestedNodeFeatureGroups (containsGroups), letting the switch hierarchy (leaf ⊂ spine ⊂ core) be expressed by reference instead of duplicating node lists — important for etcd object-size limits at scale. The Topograph-side design is drafted in thenfdengine SDD (#382).An open design question runs through this:
NodeFeatureGroupexposes precomputed groups, so a scheduler must choose among them, whereas the label model (and KEP-5732's label-keyedTopologyConstraint, §3) compares values natively. Contributions that advance the NFD proposals, thenfdengine, and this labels-vs-groups trade-off help determine how topology awareness is consumed across the ecosystem.How to engage
CONTRIBUTING.mdfor mechanics (DCO sign-off, conventional commits, pre-push checks) andAGENTS.mdfor structural conventionsMaintainer note
This issue is intended to be pinned to the repository's issue tracker for discoverability. Please maintain it as the authoritative list of direction-setting focus areas; update it as items are completed, added, or reframed.