How nvidia/topograph works
Project Type and Purpose
• Topograph is a network topology service, designed to provide physical cluster network topologies so that workload managers (like SLURM or Kubernetes environments) can perform network-aware scheduling.
• Its major purpose is to listen for incoming topology requests (via an API server), observe node changes (with a node observer in Kubernetes), fetch data from various cloud or bare-metal providers (via provider modules), and then convert or translate that information (via the engine) to the appropriate format for consumption.
Major Components & Their Roles (as seen in both the README and file structure)
• API Server – Listens for HTTP requests on a defined port and triggers provider operations when a topology generation request is received.
• Node Observer – Specifically included for Kubernetes deployments, it monitors node status changes and signals the API Server to initiate a topology configuration update.
• Provider – This component interacts with various Cloud Service Providers (like AWS, GCP, OCI, CoreWeave, or Bare Metal) to fetch raw topology data and convert it into an internal representation.
• Engine – Translates the internal representation into a final output expected by the workload scheduler (e.g., SLURM or Kubernetes ConfigMap).
• Additionally, note the presence of “cmd” directories for each main executable (node-observer, topograph, toposim) that launch these components, indicating execution entry points.
• Supporting Libraries, Modules, and Interactions: The extensive “pkg”, “internal”, and “protos” directories indicate how configuration, engine logic, provider interfaces, and network communication (including gRPC) are structured.