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

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
namestring · max: 253Required
domainstring · max: 253Optional
versionstring · max: 50Optional
Responses
201

Created

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

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 clusters minimal data

get

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

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

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
namestring · max: 253Required
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
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.

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"
        }
      ],
      "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
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://charts.example.com",
  "clientSecret": "ABC333DDD"
}
PreviousSettingsNextDepartments

Last updated