feat: nscale api change

CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Changed
+
+- The `nscale` provider's Slurm auto-discovery no longer requires a statically configured `placementId`. It now lists placements for the credentialed organization and region via the Nscale Placements API, then queries the Placement Servers API for each placement and merges the results into the instance-to-node map.
+
+### Removed
+
+- `nscale` provider `placementId` parameter — placements are discovered dynamically instead. `region` credential is now required whenever Slurm auto-discovery (`Instances2NodeMap`) is used.
+
 ### Added
 
 - Documentation diagrams for architecture, Kubernetes, Slinky, Slurm topology formats, and engine outputs now ship as community-variant SVG and PNG assets with automatic dark/light mode switching (`<picture>` / `prefers-color-scheme` in docs; `#gh-light-mode-only` / `#gh-dark-mode-only` in README).

docs/providers/nscale.md

@@ -2,25 +2,26 @@
 
 The `nscale` topology provider reads topology data from the Nscale Radar API and converts it into Topograph's canonical three-tier topology graph.
 
-The provider uses two Nscale APIs:
+The provider uses three Nscale APIs:
 
 - **Radar API**: returns each instance's network path via `GET /v1/topology`
-- **Instance API**: returns instance metadata via `GET /v2/instances?organizationID=<org>&regionID=<region>`
+- **Placements API**: lists the organization's placements in a region via `GET /api/v2/placements`
+- **Placement Servers API**: returns server metadata for a placement via `GET /api/v2/placements/{placementID}/servers`
 
-The Radar response supplies the provider instance ID, switch path, and optional block ID. The Instance API response maps provider instance IDs to hostnames using `metadata.id` and `metadata.name`; this is used by the Slurm engine when Topograph discovers Slurm nodes automatically.
+The Radar response supplies the provider instance ID, switch path, and optional block ID. For Slurm auto-discovery, the provider lists every placement for the configured organization and region, then queries the Placement Servers API for each one and merges the results into a single instance-ID-to-hostname map using `metadata.id` and `metadata.name`.
 
 ## When to Use This Provider
 
 Use this provider for Nscale environments where Radar is the topology source. It is most commonly used with the Slurm engine to generate `topology.conf` from the current Slurm node list.
 
-If the request payload supplies explicit `nodes`, Topograph uses those instance ID to node name mappings directly. If `nodes` is omitted and the Slurm engine is used, Topograph runs `scontrol show nodes -o`, asks the Nscale Instance API for the instance catalog in the configured region, and keeps entries whose `metadata.name` matches a Slurm node name.
+If the request payload supplies explicit `nodes`, Topograph uses those instance ID to node name mappings directly. If `nodes` is omitted and the Slurm engine is used, Topograph runs `scontrol show nodes -o`, lists the organization's placements in the configured region via the Nscale Placements API, and asks the Placement Servers API for the server catalog of each placement. When `scontrol` returns a non-empty node list, only entries whose `metadata.name` exactly matches a Slurm node name are kept; if the node list is empty, every placement-server mapping is kept.
 
 ## Prerequisites
 
 - A Radar API endpoint reachable from the Topograph host
-- An Instance API endpoint reachable from the Topograph host
+- A Placements / Placement Servers API endpoint reachable from the Topograph host
 - An Nscale organization ID
-- An API token with permission to read topology and instance metadata
+- An API token with permission to read topology, placements, and placement server metadata
 - The Nscale region ID for the cluster
 - For Slurm auto-discovery, `scontrol` must be available to the Topograph process
 
@@ -29,8 +30,8 @@ If the request payload supplies explicit `nodes`, Topograph uses those instance
 | Field | Required | Description |
 |---|---|---|
 | `org` | Yes | Nscale organization ID |
-| `token` | Yes | Bearer token used for Radar and Instance API requests |
-| `region` | Required for Slurm auto-discovery | Nscale region ID used for Instance API lookup and Slurm region assignment |
+| `token` | Yes | Bearer token used for Radar, Placements, and Placement Servers API requests |
+| `region` | Required for Slurm auto-discovery | Nscale region ID used for Slurm region assignment and to scope the Placements API listing |
 
 Store credentials in a YAML file:
 
@@ -53,7 +54,7 @@ Credentials can also be supplied directly in the topology request payload under
 | Field | Required | Description |
 |---|---|---|
 | `radarApiUrl` | Yes | Base URL for the Radar API, for example `https://radar.example.com` |
-| `instanceApiUrl` | Yes | Base URL for the Instance API, for example `https://api.example.com` |
+| `instanceApiUrl` | Yes | Base URL for the Placements and Placement Servers APIs, for example `https://api.example.com` |
 | `trimTiers` | No | Number of highest topology tiers to trim from output. Defaults to `0` |
 
 The top-level Topograph `pageSize` setting controls pagination for the Radar topology request.
@@ -159,31 +160,75 @@ Each returned instance is translated as follows:
 | `network_node_path[2]` | Leaf tier |
 | `block_id` | Accelerator / NVLink domain |
 
-For Slurm auto-discovery, the provider also fetches instance metadata:
+For Slurm auto-discovery, the provider first lists the organization's placements in the configured region from the Placements API:
 
 ```text
-GET <instanceApiUrl>/v2/instances?organizationID=<org>&regionID=<region>
+GET <instanceApiUrl>/api/v2/placements?organizationID=<org>&regionID=<region>
 Authorization: Bearer <token>
 ```
 
+The response is an array of placement objects; the provider extracts `metadata.id` from each entry. It then fetches server metadata from the Placement Servers API for every placement ID returned:
+
+```text
+GET <instanceApiUrl>/api/v2/placements/<placementId>/servers
+Authorization: Bearer <token>
+```
+
+The response is an array of placement server objects. The provider extracts `metadata.id` (the server's unique identifier) and `metadata.name` (the hostname) from each entry and merges them across all placements into a single instance-ID-to-hostname map.
+
 It builds the same map produced by:
 
 ```bash
-curl -s -H "Authorization: Bearer $TOKEN" \
-  "$INSTANCE_API_URL/v2/instances?organizationID=$ORG&regionID=$REGION" \
-  | jq -r '.[] | "\(.metadata.id)\t\(.metadata.name)"'
+set -euo pipefail
+
+placement_ids=$(curl --fail --show-error --silent -H "Authorization: Bearer $TOKEN" \
+  "$INSTANCE_API_URL/api/v2/placements?organizationID=$ORG_ID&regionID=$REGION_ID" \
+  | jq -er '.[] | select(.metadata.id != "") | .metadata.id')
+
+for placement_id in $placement_ids; do
+  curl --fail --show-error --silent -H "Authorization: Bearer $TOKEN" \
+    "$INSTANCE_API_URL/api/v2/placements/$placement_id/servers" \
+    | jq -er '.[] | select(.metadata.id != "" and .metadata.name != "") | "\(.metadata.id)\t\(.metadata.name)"'
+done
 ```
 
 ## Verifying the Output
 
-First verify that the Instance API returns the hostnames Slurm knows:
+When Slurm's node list (`scontrol show nodes -o`) is non-empty, `Instances2NodeMap`
+only keeps a Placement Server entry when its `metadata.name` is an exact match for a
+Slurm node name — there is no fuzzy or partial matching. If the node list is empty,
+no filtering is applied and every placement-server mapping is retained. Before
+triggering topology generation, compare the hostnames returned by the Placements and
+Placement Servers APIs against Slurm's own node list and fail if they differ:
 
 ```bash
-curl -s -H "Authorization: Bearer $TOKEN" \
-  "$INSTANCE_API_URL/v2/instances?organizationID=$ORG&regionID=$REGION" \
-  | jq -r '.[] | "\(.metadata.id)\t\(.metadata.name)"'
+set -euo pipefail
+
+slurm_nodes=$(scontrol show nodes -o | grep -oE 'NodeName=[^ ]+' | cut -d= -f2 | sort -u)
+[ -n "$slurm_nodes" ] || { echo "FAIL: scontrol returned no nodes"; exit 1; }
+
+placement_ids=$(curl --fail --show-error --silent -H "Authorization: Bearer $TOKEN" \
+  "$INSTANCE_API_URL/api/v2/placements?organizationID=$ORG_ID&regionID=$REGION_ID" \
+  | jq -er '.[] | select(.metadata.id != "") | .metadata.id')
+
+placement_hostnames=$(for placement_id in $placement_ids; do
+  curl --fail --show-error --silent -H "Authorization: Bearer $TOKEN" \
+    "$INSTANCE_API_URL/api/v2/placements/$placement_id/servers" \
+    | jq -er '.[] | select(.metadata.id != "" and .metadata.name != "") | .metadata.name'
+done | sort -u)
+
+if diff <(printf '%s\n' "$slurm_nodes") <(printf '%s\n' "$placement_hostnames"); then
+  echo "OK: Placement Server hostnames match Slurm's node list"
+else
+  echo "FAIL: Placement Server hostnames differ from Slurm's node list"
+  exit 1
+fi
 ```
 
+If the two lists differ, `Instances2NodeMap` will silently drop the mismatched nodes
+from the generated topology rather than erroring, so this check should be run before
+relying on Slurm auto-discovery.
+
 Then trigger topology generation:
 
 ```bash

pkg/providers/nscale/provider.go

@@ -22,8 +22,9 @@ import (
 const (
 	NAME = "nscale"
 
-	urlTopologyPath  = "/v1/topology"
-	urlInstancesPath = "/v2/instances"
+	urlTopologyPath         = "/v1/topology"
+	urlPlacementsPath       = "/api/v2/placements"
+	urlPlacementServersPath = "/api/v2/placements/%s/servers"
 )
 
 type baseProvider struct {
@@ -46,10 +47,11 @@ type Credentials struct {
 
 type Client interface {
 	Topology(context.Context, string, int, int) ([]InstanceTopology, error)
-	Instances(context.Context, string) (map[string]string, error)
+	ListPlacements(ctx context.Context, org, region string) ([]string, error)
+	PlacementServers(context.Context, string) (map[string]string, error)
 }
 
-// nscaleClient is a topology and instance API client.
+// nscaleClient is a Radar topology, Placements, and Placement Servers API client.
 type nscaleClient struct {
 	radarAPIURL    string
 	instanceAPIURL string
@@ -69,11 +71,19 @@ type TopologyResult struct {
 	Instances []InstanceTopology `json:"results"`
 }
 
-type instance struct {
-	Metadata instanceMetadata `json:"metadata"`
+type placement struct {
+	Metadata placementMetadata `json:"metadata"`
 }
 
-type instanceMetadata struct {
+type placementMetadata struct {
+	ID string `json:"id"`
+}
+
+type placementServer struct {
+	Metadata placementServerMetadata `json:"metadata"`
+}
+
+type placementServerMetadata struct {
 	ID   string `json:"id"`
 	Name string `json:"name"`
 }
@@ -103,32 +113,60 @@ func (c *nscaleClient) Topology(ctx context.Context, region string, pageSize, of
 	return resp.Instances, nil
 }
 
-func (c *nscaleClient) Instances(ctx context.Context, region string) (map[string]string, error) {
+func (c *nscaleClient) ListPlacements(ctx context.Context, org, region string) ([]string, error) {
 	headers := map[string]string{
 		"Authorization": "Bearer " + c.token,
 	}
 	query := map[string]string{
-		"organizationID": c.org,
+		"organizationID": org,
 		"regionID":       region,
 	}
-	f := httpreq.GetRequestFunc(ctx, http.MethodGet, headers, query, nil, c.instanceAPIURL, urlInstancesPath)
+	f := httpreq.GetRequestFunc(ctx, http.MethodGet, headers, query, nil, c.instanceAPIURL, urlPlacementsPath)
 
 	body, httpErr := httpreq.DoRequestWithRetries(f, false)
 	if httpErr != nil {
 		return nil, httpErr
 	}
 
-	instances := []instance{}
-	if err := json.Unmarshal(body, &instances); err != nil {
+	placements := []placement{}
+	if err := json.Unmarshal(body, &placements); err != nil {
 		return nil, httperr.NewError(http.StatusBadGateway, err.Error())
 	}
 
-	i2n := make(map[string]string, len(instances))
-	for _, instance := range instances {
-		if instance.Metadata.ID == "" || instance.Metadata.Name == "" {
+	ids := make([]string, 0, len(placements))
+	for _, p := range placements {
+		if p.Metadata.ID == "" {
+			continue
+		}
+		ids = append(ids, p.Metadata.ID)
+	}
+
+	return ids, nil
+}
+
+func (c *nscaleClient) PlacementServers(ctx context.Context, placementID string) (map[string]string, error) {
+	headers := map[string]string{
+		"Authorization": "Bearer " + c.token,
+	}
+	path := fmt.Sprintf(urlPlacementServersPath, placementID)
+	f := httpreq.GetRequestFunc(ctx, http.MethodGet, headers, nil, nil, c.instanceAPIURL, path)
+
+	body, httpErr := httpreq.DoRequestWithRetries(f, false)
+	if httpErr != nil {
+		return nil, httpErr
+	}
+
+	servers := []placementServer{}
+	if err := json.Unmarshal(body, &servers); err != nil {
+		return nil, httperr.NewError(http.StatusBadGateway, err.Error())
+	}
+
+	i2n := make(map[string]string, len(servers))
+	for _, s := range servers {
+		if s.Metadata.ID == "" || s.Metadata.Name == "" {
 			continue
 		}
-		i2n[instance.Metadata.ID] = instance.Metadata.Name
+		i2n[s.Metadata.ID] = s.Metadata.Name
 	}
 
 	return i2n, nil
@@ -212,10 +250,22 @@ func (p *Provider) Instances2NodeMap(ctx context.Context, nodes []string) (map[s
 		return nil, fmt.Errorf("missing 'region'")
 	}
 
-	instances, err := p.client.Instances(ctx, p.creds.Region)
+	placementIDs, err := p.client.ListPlacements(ctx, p.creds.Org, p.creds.Region)
 	if err != nil {
-		return nil, fmt.Errorf("failed to get instances: %v", err)
+		return nil, fmt.Errorf("failed to list placements: %w", err)
 	}
+
+	instances := make(map[string]string)
+	for _, placementID := range placementIDs {
+		servers, err := p.client.PlacementServers(ctx, placementID)
+		if err != nil {
+			return nil, fmt.Errorf("failed to get placement servers for placement %s: %w", placementID, err)
+		}
+		for id, node := range servers {
+			instances[id] = node
+		}
+	}
+
 	if len(nodes) == 0 {
 		return instances, nil
 	}

pkg/providers/nscale/provider_sim.go

@@ -67,7 +67,11 @@ func (c *simClient) Topology(ctx context.Context, _ string, pageSize, offset int
 	return resp, nil
 }
 
-func (c *simClient) Instances(_ context.Context, _ string) (map[string]string, error) {
+func (c *simClient) ListPlacements(_ context.Context, _, _ string) ([]string, error) {
+	return []string{"sim"}, nil
+}
+
+func (c *simClient) PlacementServers(_ context.Context, _ string) (map[string]string, error) {
 	i2n := make(map[string]string, len(c.model.Nodes))
 	for _, node := range c.model.Nodes {
 		i2n[node.ID] = node.ID