NVIDIA Run:ai

Network Topologies

The Network Topologies API enables administrators to reflect the hierarchical network topology connectivity of nodes in a data center, such as racks, blocks, and other organizational units, to improve pod scheduling decisions for communication-intensive AI/ML workloads. To support topology-aware scheduling, this API allows administrators to define a multi-level network topology element using ordered Kubernetes node labels that represent the network connectivity of nodes in the data center. Nodes are labeled with the same key-value pairs labels that represent their location in the data center network. These labels are used by the NVIDIA Run:ai Scheduler to prefer scheduling pods on nodes that are "closer" to each other, minimizing communication overhead and optimizing workload performance.

Get network topologies.

Retrieve a list of network topologies with details.

SecuritybearerAuth
Request
query Parameters
filterBy
Array of strings

Filter results by a parameter. Use the format field-name operator value. Supported operators: == Equals != Not equals <= Less than or equal >= Greater than or equal =@ Contains !@ Does not contain =^ Starts with =$ Ends with Date values must be in ISO 8601 timestamp format. Only the following operators support dates: ==, !=, <=, >=.

Example: filterBy=clusterId==123e4567-e89b-12d3-a456-426614174000,source=@Run.ai
Responses
200

Executed successfully.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

get/api/v1/network-topologies
Response samples
application/json
{
  • "networkTopologies": [
    ]
}

Create network topologies

Creates a network topology object based on the provided specification.

SecuritybearerAuth
Request
Request Body schema: application/json
required

The network topology to create.

levels
required
Array of strings (NetworkTopologyLevels)

Ordered array of network topology levels

name
required
string (NetworkTopologyName) [ 1 .. 63 ] characters ^[a-z]([a-z0-9-]*[a-z0-9])?$

Name of the network topology

clusterId
required
string <uuid> (ClusterId)

The id of the cluster.

Responses
201

Created

400

Bad request.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

post/api/v1/network-topologies
Request samples
application/json
{
  • "levels": [
    ],
  • "name": "default-topology",
  • "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210"
}
Response samples
application/json
{
  • "levels": [
    ],
  • "name": "default-topology",
  • "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "tenantId": 1001,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "user@lab.com",
  • "phase": "Ready",
  • "source": "Run.ai"
}

Count the amount of network topologies in a tenant.

Retrieve the count of network topologies in a tenant group by selected attributes

SecuritybearerAuth
Request
query Parameters
filterBy
Array of strings

Filter results by a parameter. Use the format field-name operator value. Supported operators: == Equals != Not equals <= Less than or equal >= Greater than or equal =@ Contains !@ Does not contain =^ Starts with =$ Ends with Date values must be in ISO 8601 timestamp format. Only the following operators support dates: ==, !=, <=, >=.

Example: filterBy=clusterId==123e4567-e89b-12d3-a456-426614174000,source=@Run.ai
Responses
200

Executed successfully.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

get/api/v1/network-topologies/count
Response samples
application/json
{
  • "count": 1
}

Get network topology by id.

Retrieve network topology details by Universally Unique Identifier (UUID).

SecuritybearerAuth
Request
path Parameters
networkTopologyId
required
string <uuid>

The unique identifier for the network topology

Example: 123e4567-e89b-12d3-a456-426614174000
Responses
200

Executed successfully.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

get/api/v1/network-topologies/{networkTopologyId}
Response samples
application/json
{
  • "levels": [
    ],
  • "name": "default-topology",
  • "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "tenantId": 1001,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "user@lab.com",
  • "phase": "Ready",
  • "source": "Run.ai"
}

Delete network topology by ID.

Delete an existing network topology by its ID.

SecuritybearerAuth
Request
path Parameters
networkTopologyId
required
string <uuid>

The unique identifier for the network topology

Example: 123e4567-e89b-12d3-a456-426614174000
Responses
204

No Content.

401

Unauthorized

403

Forbidden

404

The specified resource was not found

500

unexpected error

503

unexpected error

delete/api/v1/network-topologies/{networkTopologyId}
Response samples
application/json
{
  • "code": 401,
  • "message": "Issuer is not familiar."
}
➔ Next to Access rules