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

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

namestringRequired

domainstringOptional

versionstringOptional

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 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

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

namestringRequired

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

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"
}

Get cluster installation file by id.

get

Retrieve the installation values file of a cluster by Retrieve the installation values file of a given cluster by ID. Supports clusters 2.13 and lower.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

cluster_uuidstring · uuidRequired

Unique identifier of the cluster.

Query parameters

cloudstring · enumOptional

Cloud type identifier.

Possible values:

clusteripstringOptional

Comma-separated list of IP addresses that provide access to the cluster.

formatstring · enumOptional

Format of the output file.

Default: yamlPossible values:

Responses

200

OK

application/json

Responsestring · text

401

Unauthorized

application/json

404

The specified resource was not found

application/json

get

/v1/k8s/clusters/{cluster_uuid}/installfile

HTTPcURLJavaScriptPython

GET /v1/k8s/clusters/{cluster_uuid}/installfile HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

text

Deprecated

Get cluster metrics.

get

Get current cluster metrics. If time range query parameters supplied, then historical data will be returned as well. Deprecated - please use api/v1/clusters/{clusterUuid}/metrics

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-timeOptional

Start of time range to fetch data from in UTC format.

Example: 2023-06-06 12:09:18.211

endstring · date-timeOptional

End of time range to fetch data from in UTC format.

Example: 2023-06-07 12:09:18.211

numberOfSamplesinteger · max: 1000Optional

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

Default: 20Example: 20

nodepoolNamestringOptional

Filter by unique nodepool name.

Example: default

Responses

200

A Clusters metrics

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

get

/v1/k8s/clusters/{clusterUuid}/metrics

HTTPcURLJavaScriptPython

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

{
  "metadata": {
    "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
    "clusterName": "cluster-a"
  },
  "current": {
    "resources": [
      {
        "numberOfPendingWorkloads": 1,
        "gpu": {
          "quota": 3,
          "allocated": 2.5,
          "utilization": 0.765
        },
        "cpu": {
          "quota": 3,
          "allocated": 2.5,
          "utilization": 0.765
        },
        "memory": {
          "quota": 3,
          "allocated": 2.5,
          "utilization": 0.765
        },
        "nodepoolName": "nodepoola"
      }
    ],
    "projectResources": [
      {
        "numberOfPendingWorkloads": 1,
        "gpu": {
          "quota": 3,
          "allocated": 2.5,
          "utilization": 0.765
        },
        "cpu": {
          "quota": 3,
          "allocated": 2.5,
          "utilization": 0.765
        },
        "memory": {
          "quota": 3,
          "allocated": 2.5,
          "utilization": 0.765
        },
        "projectName": "project-a",
        "departmentName": "default",
        "nodepoolName": "nodepoola"
      }
    ]
  },
  "timeRange": {
    "resources": [
      {
        "numberOfPendingWorkloads": 1,
        "gpu": {
          "quota": 3,
          "allocated": 2.5,
          "utilization": 0.765
        },
        "cpu": {
          "quota": 3,
          "allocated": 2.5,
          "utilization": 0.765
        },
        "memory": {
          "quota": 3,
          "allocated": 2.5,
          "utilization": 0.765
        },
        "timestamp": "2023-06-06T12:09:18.211Z"
      }
    ]
  }
}