Clusters

Use these endpoints to create, manage and delete NVIDIA Run:ai Kubernetes clusters.

Get a list of clusters.

get

Retrieve a list of clusters with details.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Query parameters

verbositystring · enumOptional

response verbosity level.

Default: fullExample: fullPossible values:

includeRequestedForDeletebooleanOptional

When true, includes clusters that are marked for deletion

Example: true

Responses

200

Executed successfully.

application/json

uuidstring · uuidRequired

tenantIdinteger · int32Required

The id of the tenant.

Example: 1001

namestring · min: 1 · max: 253Required

createdAtstring · date-timeRequired

domainstring · min: 1 · max: 253 · nullableOptional

versionstring · min: 1 · max: 50 · nullableOptional

updatedAtstring · date-time · nullableOptional

deletedAtstring · date-time · nullableOptional

lastLivenessstring · date-time · nullableOptional

deleteRequestedAtstring · date-time · nullableOptional

the timestamp value of when the cluster deletion request was received

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

500

unexpected error

application/json

503

unexpected error

application/json

get

/api/v1/clusters

HTTPcURLJavaScriptPython

GET /api/v1/clusters HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "uuid": "A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11",
    "name": "example",
    "tenantId": 1001,
    "domain": "my.company.com",
    "status": {},
    "createdAt": "2020-01-01T00:00:00Z",
    "updatedAt": "2020-01-02T00:00:00Z",
    "lastLiveness": "2020-01-02T00:00:00Z",
    "version": "2.15.0"
  }
]

Create a cluster.

post

Use to create a Kubernetes cluster.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Body

application/json

namestring · max: 253Required

domainstring · max: 253Optional

versionstring · max: 50Optional

Responses

201

Created

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

500

unexpected error

application/json

503

unexpected error

application/json

post

/api/v1/clusters

HTTPcURLJavaScriptPython

POST /api/v1/clusters HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "name": "text",
  "domain": "text",
  "version": "text"
}

{
  "uuid": "A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11",
  "name": "example",
  "tenantId": 1001,
  "domain": "my.company.com",
  "status": {},
  "createdAt": "2020-01-01T00:00:00Z",
  "updatedAt": "2020-01-02T00:00:00Z",
  "lastLiveness": "2020-01-02T00:00:00Z",
  "version": "2.15.0"
}

Get clusters minimal data

get

Retrieve essential cluster data required for common operations (e.g., workload submission)

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Query parameters

filterBystring[] · max: 10Optional

Filter clusters by a parameter. Use the format field-name operator value. Operators are == Equals, != Not equals, <= Less than or equal, >= Greater than or equal. Dates are in ISO 8601 timestamp format and available for operators ==, !=, <= and >=.

Example: ["name==my-cluster"]

offsetinteger · int32Optional

The offset of the first item returned in the collection.

Example: 100

limitinteger · int32 · min: 1 · max: 500Optional

The maximum number of entries to return.

Default: 50

Responses

200

ok

application/json

400

Bad request.

application/json

503

unexpected error

application/json

get

/api/v1/clusters/minimal

HTTPcURLJavaScriptPython

GET /api/v1/clusters/minimal HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "clusters": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "tenantId": 1001,
      "version": "text",
      "domain": "text",
      "platform": {
        "type": "vanilla",
        "kubeVersion": "text"
      },
      "state": "WaitingToConnect",
      "ingressClass": "nginx",
      "dependenciesStatus": {
        "required": {
          "ANY_ADDITIONAL_PROPERTY": {
            "available": true,
            "reason": "text",
            "components": "[Circular Reference]"
          }
        },
        "optional": {
          "ANY_ADDITIONAL_PROPERTY": {
            "available": true,
            "reason": "text",
            "components": "[Circular Reference]"
          }
        }
      }
    }
  ]
}

Get cluster minimal data by id

get

Retrieve essential data for a specific cluster by ID required for common operations (e.g., workload submission)

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

clusterUuidstring · uuid · min: 1Required

The Universally Unique Identifier (UUID) of the cluster.

Example: 9f55255e-11ed-47c7-acef-fc4054768dbc

Responses

200

ok

application/json

uuidstring · uuidRequired

namestring · .*Required

tenantIdinteger · int32Required

The id of the tenant.

Example: 1001

versionstring · .* · nullableOptional

domainstring · .* · nullableOptional

statestring · enumOptional

The cluster's state.

Possible values:

ingressClassstring · nullableOptional

the ingress class that is configured for the cluster

Example: nginx

400

Bad request.

application/json

404

The specified resource was not found

application/json

503

unexpected error

application/json

get

/api/v1/clusters/{clusterUuid}/minimal

HTTPcURLJavaScriptPython

GET /api/v1/clusters/{clusterUuid}/minimal HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "tenantId": 1001,
  "version": "text",
  "domain": "text",
  "platform": {
    "type": "vanilla",
    "kubeVersion": "text"
  },
  "state": "WaitingToConnect",
  "ingressClass": "nginx",
  "dependenciesStatus": {
    "required": {
      "ANY_ADDITIONAL_PROPERTY": {
        "available": true,
        "reason": "text",
        "components": {
          "ANY_ADDITIONAL_PROPERTY": {
            "available": true,
            "reason": "text",
            "components": "[Circular Reference]"
          }
        }
      }
    },
    "optional": {
      "ANY_ADDITIONAL_PROPERTY": {
        "available": true,
        "reason": "text",
        "components": {
          "ANY_ADDITIONAL_PROPERTY": {
            "available": true,
            "reason": "text",
            "components": "[Circular Reference]"
          }
        }
      }
    }
  }
}

Get cluster by id.

get

Retrieve cluster details by Universally Unique Identifier (UUID).

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

clusterUuidstring · uuid · min: 1Required

The Universally Unique Identifier (UUID) of the cluster.

Example: 9f55255e-11ed-47c7-acef-fc4054768dbc

Query parameters

verbositystring · enumOptional

response verbosity level.

Default: fullExample: fullPossible values:

Responses

200

Executed successfully.

application/json

uuidstring · uuidRequired

tenantIdinteger · int32Required

The id of the tenant.

Example: 1001

namestring · min: 1 · max: 253Required

createdAtstring · date-timeRequired

domainstring · min: 1 · max: 253 · nullableOptional

versionstring · min: 1 · max: 50 · nullableOptional

updatedAtstring · date-time · nullableOptional

deletedAtstring · date-time · nullableOptional

lastLivenessstring · date-time · nullableOptional

deleteRequestedAtstring · date-time · nullableOptional

the timestamp value of when the cluster deletion request was received

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

500

unexpected error

application/json

503

unexpected error

application/json

get

/api/v1/clusters/{clusterUuid}

HTTPcURLJavaScriptPython

GET /api/v1/clusters/{clusterUuid} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "uuid": "A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11",
  "name": "example",
  "tenantId": 1001,
  "domain": "my.company.com",
  "status": {},
  "createdAt": "2020-01-01T00:00:00Z",
  "updatedAt": "2020-01-02T00:00:00Z",
  "lastLiveness": "2020-01-02T00:00:00Z",
  "version": "2.15.0"
}

Update a cluster by id.

put

Use to update the details of a Kubernetes cluster by Universally Unique Identifier (UUID).

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

clusterUuidstring · uuid · min: 1Required

The Universally Unique Identifier (UUID) of the cluster.

Example: 9f55255e-11ed-47c7-acef-fc4054768dbc

Body

application/json

namestring · max: 253Required

Responses

204

No Content.

400

Bad request.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

unexpected error

application/json

503

unexpected error

application/json

put

/api/v1/clusters/{clusterUuid}

HTTPcURLJavaScriptPython

PUT /api/v1/clusters/{clusterUuid} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "name": "text"
}

No content

Delete a cluster by id.

delete

Use to delete a cluster by Universally Unique Identifier (UUID). Will return 202 for success if this api was called on a cluster that its version is >=2.20, and force query param is false or not provided. Will return 204 for success if force query param is true, or if cluster is in a version < 2.20

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

clusterUuidstring · uuid · min: 1Required

The Universally Unique Identifier (UUID) of the cluster.

Example: 9f55255e-11ed-47c7-acef-fc4054768dbc

Query parameters

forcebooleanOptional

if true will force cluster instant deletion otherwise will start cluster graceful deletion process.

Default: falseExample: true

Responses

202

Accepted.

application/json

204

No Content.

401

Unauthorized

application/json

403

Forbidden

application/json

500

unexpected error

application/json

503

unexpected error

application/json

delete

/api/v1/clusters/{clusterUuid}

HTTPcURLJavaScriptPython

DELETE /api/v1/clusters/{clusterUuid} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "code": 202,
  "message": "Request has been accepted."
}

Get the cluster metrics data.

get

Retrieve the metrics data for a Kubernetes cluster by Universally Unique Identifier (UUID).

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

clusterUuidstring · uuid · min: 1Required

The Universally Unique Identifier (UUID) of the cluster.

Example: 9f55255e-11ed-47c7-acef-fc4054768dbc

Query parameters

startstring · date-timeRequired

Start date of time range to fetch data in ISO 8601 timestamp format.

Example: 2023-06-06T12:09:18.211Z

endstring · date-timeRequired

End date of time range to fetch data in ISO 8601 timestamp format.

Example: 2023-06-07T12:09:18.211Z

numberOfSamplesinteger · max: 1000Optional

The number of samples to take in the specified time range.

Default: 20Example: 20

groupBystring · enumOptional

Labels to group the returned metrics data by. Grouping availability depends on the selected metric type. Supported values: "category" (workload category) or "node pool".

Example: CategoryPossible values:

nodepoolNamestringOptional

Filter using the nodepool.

Example: default

Responses

200

Executed successfully.

application/jsontext/csv

207

Partial success.

application/json

400

Bad request.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

422

Unprocessable entity - The request was well-formed but contains semantic errors.

application/json

500

unexpected error

application/json

503

unexpected error

application/json

get

/api/v1/clusters/{clusterUuid}/metrics

HTTPcURLJavaScriptPython

GET /api/v1/clusters/{clusterUuid}/metrics?start=2023-06-06T12%3A09%3A18.211Z&end=2023-06-07T12%3A09%3A18.211Z&metricType=TOTAL_GPU_NODES HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "measurements": [
    {
      "type": "ALLOCATED_GPU",
      "labels": "{'gpu': '3'}",
      "values": [
        {
          "value": "85",
          "timestamp": "2023-06-06 12:09:18.211"
        }
      ],
      "groups": [
        {
          "key": "Nodepool",
          "value": "gpu-pool-1"
        }
      ]
    }
  ]
}

Retrieve the installation instructions of a cluster by ID.

get

Use to retrieve installation instruction for a cluster by Universally Unique Identifier (UUID). Supports clusters version 2.15 or above.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

clusterUuidstring · uuid · min: 1Required

The Universally Unique Identifier (UUID) of the cluster.

Example: 9f55255e-11ed-47c7-acef-fc4054768dbc

Query parameters

versionstringRequired

The cluster version to install

Example: 2.16

remoteClusterUrlstringOptional

The remote URL of the runai cluster

Example: https://cluster.runai

Responses

200

Executed successfully.

application/json

installationStrstringRequired

repositoryNamestringRequired

chartRepoURLstringRequired

clientSecretstringRequired

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

500

unexpected error

application/json

503

unexpected error

application/json

get

/api/v1/clusters/{clusterUuid}/cluster-install-info

HTTPcURLJavaScriptPython

GET /api/v1/clusters/{clusterUuid}/cluster-install-info?version=2.16 HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "installationStr": "helm update --update repo/runai-cluster -n runai --set cluster.url=test_cluster",
  "repositoryName": "runai",
  "chartRepoURL": "https://runai.jfrog.io/artifactory/charts",
  "clientSecret": "ABC333DDD"
}