Version 2.21 has reached end of support. Upgrade to a newer supported version.
Ctrlk
Contact support
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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
AuthorizationstringRequired

Bearer authentication

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
namestringRequired
createdAtstring · date-timeRequired
domainstring · nullableOptional
versionstring · 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

get/api/v1/clusters
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
AuthorizationstringRequired

Bearer authentication

Body
namestringRequired
domainstringOptional
versionstringOptional
Responses
201

Created

application/json
uuidstring · uuidRequired
tenantIdinteger · int32Required

The id of the tenant.

Example: 1001
namestringRequired
createdAtstring · date-timeRequired
domainstring · nullableOptional
versionstring · 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

post/api/v1/clusters
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
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
namestringRequired
createdAtstring · date-timeRequired
domainstring · nullableOptional
versionstring · 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

get/api/v1/clusters/{clusterUuid}
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
AuthorizationstringRequired

Bearer authentication

Path parameters
clusterUuidstring · uuid · min: 1Required

The Universally Unique Identifier (UUID) of the cluster.

Example: 9f55255e-11ed-47c7-acef-fc4054768dbc
Body
namestringRequired
Responses
204

No Content.

No content
put/api/v1/clusters/{clusterUuid}
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
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
codeinteger · min: 100 · max: 599Required
messagestringRequired
delete/api/v1/clusters/{clusterUuid}
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
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
Responses
200

Executed successfully.

get/api/v1/clusters/{clusterUuid}/metrics
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"
        }
      ]
    }
  ]
}

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
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
get/api/v1/clusters/{clusterUuid}/cluster-install-info
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
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
string · textOptional
get/v1/k8s/clusters/{cluster_uuid}/installfile
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
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
get/v1/k8s/clusters/{clusterUuid}/metrics
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"
      }
    ]
  }
}
PreviousNVIDIA Run:ai API PolicyNextDepartments

Last updated