GetGpuClusterTopology - Alibaba Cloud Linux - Alibaba Cloud Documentation Center

Operation description

After you install the component on the target ACK cluster:

When a cluster is managed for the first time, the component is installed on all ECS instances currently in the cluster. If the cluster has more than 50 nodes, only the first 50 nodes are processed in the first batch.
The operating system console periodically checks the scaling status of managed clusters. When a new ECS instance is added to a cluster, the console automatically installs the component on it without requiring manual intervention.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

No authorization for this operation. If you encounter issues with this operation, contact technical support.

Request syntax

GET /api/v1/aiTopology/topology/clusterTopology HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
clusterId	string	Yes	The cluster name. Select a cluster from the cluster list returned by the GetListGpuCluster operation.	"cluster1"
startTime	string	No	The timestamp for the query. Defaults to the current time. Must be a second-level timestamp.	1709740800
instanceIdList	any	No	The GPU topology information for the specified list of instances.	["instance1", "instance2","instance3"]
podList	any	No	The GPU topology information for the specified list of pods.	["pod1", "pod2","pod3"]
taskIdList	any	No	The GPU topology information for the specified list of nodes.	["task1", "task2"]
communicationId	string	No	Used when viewing collective communication topology. Specifies the topology relationship for a given communication group ID, such as the inter-rank communication topology (tree or ring topology) within a communication group. Must be used together with channel_id and topo_type. ⚠️ Use the communication filter type of the GetGpuClusterArgsOptions operation to retrieve the list of communication_id values.	communicationId =0x412523235123 channelId=1 topoType=ring
channelId	string	No	Used when viewing collective communication topology. Specifies the topology relationship for a given channel ID within a communication group, such as the inter-rank communication topology (tree or ring topology). Must be used together with communication_id and topo_type. ⚠️ Use the channel filter parameter of the GetGpuClusterArgsOptions operation to retrieve the list of channel_id values for a specified communication_id.	communicationId =0x412523235123 channelId=1 topoType=ring
topoType	string	No	Used when viewing collective communication topology. Specifies the topology relationship for a given topology type within a communication group and channel, such as the inter-rank communication topology (tree or ring topology). Must be used together with communication_id and channel_id. ⚠️ Use the topoType filter parameter of the GetGpuClusterArgsOptions operation to retrieve the list of topo_type values for a specified communication_id and channel_id.	communicationId =0x412523235123 channelId=1 topoType=ring

Response elements

Element	Type	Description	Example
	object	The response body.
code	string	The result code. Valid values: Success, Sysom.ServerError, Sysom.InvalidParameter.	Fail/Success
data	object	The data returned by the operation.
data	object	The cluster topology data structure.
edges	any	The edge data in the topology structure.	"edges": [ { "type": "GPU", "src_id": "00534a88", "dst_id": "260525e9", "values": { "Exception": [ { "key": "NCCL HANG", "value": "error0" } ], "Metric": [ { "key": "a", "value": "372201199012283428" } ], "Basic": [ { "key": "NCCL Version", "value": "v2.22.3" } ] }, "style": { "lineWidth": "0.01", "opacity": "1", "selectedStyle": "\"{\\\"opacity\\\": 1, \\\"lineWidth\\\": 1}\"", "stroke": "#e94242\n" } } ]
nodes	any	The node data in the topology structure.	"nodes": [ { "id": "i-xxxxxx", "name": "i-xxxxxx", "gpu_list": [ { "id": "6cc37fbc", "name": "GPU0", "style": { "fill": "#e94242", "opacity": "0.1" }, "values": { "Metric": [ { "key": "0", "value": "gpu_util(%)" } ], "Basic": [ { "key": "1", "value": "Gpu Number" } ], "Exception": [ { "key": "NCCL HANG", "value": "error0" } ] } } ], "style": { "fillOpacity": "0.5", "fill": "#e94242" }, "values": { "Exception": [ { "key": "NCCL HANG", "value": "error0" } ], "Basic": [ { "key": "podList", "value": "podname1" } ], "Metric": [ { "key": "instance", "value": "i-xxxxxx" } ] } } ],
total	integer	The number of GPU cards returned.	36
message	string	The error message returned when the code is not Success.	some error msg if not success，“” if success
requestId	string	Id of the request	return real request ID

Examples

Success response

JSON format

{
  "code": "Fail/Success\n",
  "data": {
    "data": {
      "edges": "      \"edges\": [\n        {\n          \"type\": \"GPU\",\n          \"src_id\": \"00534a88\",\n          \"dst_id\": \"260525e9\",\n          \"values\": {\n            \"Exception\": [\n              {\n                \"key\": \"NCCL HANG\",\n                \"value\": \"error0\"\n              }\n            ],\n            \"Metric\": [\n              {\n                \"key\": \"a\",\n                \"value\": \"372201199012283428\"\n              }\n            ],\n            \"Basic\": [\n              {\n                \"key\": \"NCCL Version\",\n                \"value\": \"v2.22.3\"\n              }\n            ]\n          },\n          \"style\": {\n            \"lineWidth\": \"0.01\",\n            \"opacity\": \"1\",\n            \"selectedStyle\": \"\\\"{\\\\\\\"opacity\\\\\\\": 1, \\\\\\\"lineWidth\\\\\\\": 1}\\\"\",\n            \"stroke\": \"#e94242\\n\"\n          }\n        }\n      ]",
      "nodes": "\"nodes\": [\n        {\n          \"id\": \"i-xxxxxx\",\n          \"name\": \"i-xxxxxx\",\n          \"gpu_list\": [\n            {\n              \"id\": \"6cc37fbc\",\n              \"name\": \"GPU0\",\n              \"style\": {\n                \"fill\": \"#e94242\",\n                \"opacity\": \"0.1\"\n              },\n              \"values\": {\n                \"Metric\": [\n                  {\n                    \"key\": \"0\",\n                    \"value\": \"gpu_util(%)\"\n                  }\n                ],\n                \"Basic\": [\n                  {\n                    \"key\": \"1\",\n                    \"value\": \"Gpu Number\"\n                  }\n                ],\n                \"Exception\": [\n                  {\n                    \"key\": \"NCCL HANG\",\n                    \"value\": \"error0\"\n                  }\n                ]\n              }\n            }\n          ],\n          \"style\": {\n            \"fillOpacity\": \"0.5\",\n            \"fill\": \"#e94242\"\n          },\n          \"values\": {\n            \"Exception\": [\n              {\n                \"key\": \"NCCL HANG\",\n                \"value\": \"error0\"\n              }\n            ],\n            \"Basic\": [\n              {\n                \"key\": \"podList\",\n                \"value\": \"podname1\"\n              }\n            ],\n            \"Metric\": [\n              {\n                \"key\": \"instance\",\n                \"value\": \"i-xxxxxx\"\n              }\n            ]\n          }\n        }\n      ],"
    },
    "total": 36
  },
  "message": "some error msg if not success，“” if success",
  "requestId": "return real request ID"
}

Error codes

HTTP status code	Error code	Error message	Description
400	Sysom.ServerError	Server error, please correct the code according to the error message. %s.	Server error, please correct the code according to the error message
400	Sysom.InvalidParameter	Invalid parameters passed when calling the interface. %s.	Invalid parameter passed when calling interface

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.