Skip to content
Open Console →

Clusters

14 endpoints under /api/v1/clusters.

GET /api/v1/clusters #

List the active organization's clusters

Responses

200 Live cluster list (read-through from the shard).
Response body
  • clustersCluster[]required
    Show fields
    • namestringrequired
    • tierstringrequired
    • kubernetesVersionstringrequired
    • replicasintegerrequired
    • meshbooleanrequired
    • datastoreobjectrequired
      Show fields
      • modestringrequired
      • sizestring
      • storageGiBinteger
      • replicasinteger
      • backupsboolean
    • phasestringrequired
    • endpointstring
    • managedLoadBalancersobjectrequired
      Show fields
      • enabledbooleanrequired
      • maxServicesintegerrequired
      • loadBalancersobject[]required
        Show fields
        • servicestringrequired
        • ipstringrequired
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (quota or org mismatch).
Response body
  • errorstringrequired
404 Unknown cluster.
Response body
  • errorstringrequired
POST /api/v1/clusters #

Create a cluster

Request body

  • namestringrequired
  • tierstring · enumrequired

    smallmediumlarge

  • kubernetesVersionstring
  • replicasinteger
  • meshboolean
  • datastoreobject
    Show fields
    • modestring · enumrequired

      shareddedicated

    • sizestring · enum

      db-smalldb-mediumdb-large

    • storageGiBinteger
    • replicasinteger
    • backupsboolean
  • managedLoadBalancersobject
    Show fields
    • enabledbooleanrequired

Responses

201 Cluster accepted for provisioning.
Response body
  • namestringrequired
  • tierstringrequired
  • kubernetesVersionstringrequired
  • replicasintegerrequired
  • meshbooleanrequired
  • datastoreobjectrequired
    Show fields
    • modestringrequired
    • sizestring
    • storageGiBinteger
    • replicasinteger
    • backupsboolean
  • phasestringrequired
  • endpointstring
  • managedLoadBalancersobjectrequired
    Show fields
    • enabledbooleanrequired
    • maxServicesintegerrequired
    • loadBalancersobject[]required
      Show fields
      • servicestringrequired
      • ipstringrequired
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (quota or org mismatch).
Response body
  • errorstringrequired
404 Unknown cluster.
Response body
  • errorstringrequired
GET /api/v1/clusters/{name} #

Cluster status (read-through)

Parameters

  • name path string required

Responses

200 The cluster, straight from the shard.
Response body
  • namestringrequired
  • tierstringrequired
  • kubernetesVersionstringrequired
  • replicasintegerrequired
  • meshbooleanrequired
  • datastoreobjectrequired
    Show fields
    • modestringrequired
    • sizestring
    • storageGiBinteger
    • replicasinteger
    • backupsboolean
  • phasestringrequired
  • endpointstring
  • managedLoadBalancersobjectrequired
    Show fields
    • enabledbooleanrequired
    • maxServicesintegerrequired
    • loadBalancersobject[]required
      Show fields
      • servicestringrequired
      • ipstringrequired
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (quota or org mismatch).
Response body
  • errorstringrequired
404 Unknown cluster.
Response body
  • errorstringrequired
PATCH /api/v1/clusters/{name} #

Upgrade and/or resize the cluster

kubernetesVersion: targets must come from the version catalog; the shard enforces no-downgrade, one-minor-per-hop, and a live node-skew check that blocks (409) naming nodes whose kubelets would be left too far behind. tier: resizes the control plane; downsizing is gated on a live headroom check (409 names the crowded component). replicas: the redundancy dial. Single-replica control planes restart briefly during any roll.

Parameters

  • name path string required

Request body

  • kubernetesVersionstring
  • tierstring
  • replicasinteger
  • managedLoadBalancersobject
    Show fields
    • enabledbooleanrequired
  • datastoreobject
    Show fields
    • sizestring · enum

      db-smalldb-mediumdb-large

    • storageGiBinteger
    • replicasinteger
    • backupsboolean

Responses

200 Upgrade accepted; the control plane rolls asynchronously.
Response body
  • namestringrequired
  • tierstringrequired
  • kubernetesVersionstringrequired
  • replicasintegerrequired
  • meshbooleanrequired
  • datastoreobjectrequired
    Show fields
    • modestringrequired
    • sizestring
    • storageGiBinteger
    • replicasinteger
    • backupsboolean
  • phasestringrequired
  • endpointstring
  • managedLoadBalancersobjectrequired
    Show fields
    • enabledbooleanrequired
    • maxServicesintegerrequired
    • loadBalancersobject[]required
      Show fields
      • servicestringrequired
      • ipstringrequired
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (quota or org mismatch).
Response body
  • errorstringrequired
404 Unknown cluster.
Response body
  • errorstringrequired
409 Blocked by the node-skew gate (or a concurrent change).
Response body
  • errorstringrequired
DELETE /api/v1/clusters/{name} #

Tear a cluster down

Parameters

  • name path string required

Responses

202 Teardown accepted (asynchronous).
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (quota or org mismatch).
Response body
  • errorstringrequired
404 Unknown cluster.
Response body
  • errorstringrequired
GET /api/v1/clusters/{name}/usage #

Live usage snapshot (metering)

Parameters

  • name path string required

Responses

200 Consumption snapshot from the metering pipeline.
Response body

object

401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (quota or org mismatch).
Response body
  • errorstringrequired
404 Unknown cluster.
Response body
  • errorstringrequired
GET /api/v1/clusters/{name}/nodes #

The cluster's attached worker nodes

Parameters

  • name path string required

Responses

200 Live worker-node list (read-through from the shard).
Response body
  • nodesNode[]required
    Show fields
    • namestringrequired
    • readybooleanrequired
    • kubeletVersionstringrequired
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (quota or org mismatch).
Response body
  • errorstringrequired
404 Unknown cluster.
Response body
  • errorstringrequired
GET /api/v1/clusters/{name}/kubeconfig #

A short-lived admin kubeconfig

Parameters

  • name path string required

Responses

200 Ready-to-use kubeconfig; the embedded token expires (re-fetch then).
Response body
  • kubeconfigstringrequired
  • expiresInintegerrequired
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (quota or org mismatch).
Response body
  • errorstringrequired
404 Unknown cluster.
Response body
  • errorstringrequired
POST /api/v1/clusters/{name}/join-tokens #

Mint a single-use node join token

Parameters

  • name path string required

Responses

201 Short-lived, single-use join token for one node.
Response body
  • joinTokenstringrequired
  • clusterstringrequired
  • expiresInintegerrequired
  • joinCommandstringrequired
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (quota or org mismatch).
Response body
  • errorstringrequired
404 Unknown cluster.
Response body
  • errorstringrequired
DELETE /api/v1/clusters/{name}/nodes/{node} #

Deregister a worker node

Parameters

  • name path string required
  • node path string required

Responses

204 Node removed across all planes.
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (quota or org mismatch).
Response body
  • errorstringrequired
404 Unknown cluster.
Response body
  • errorstringrequired
GET /api/v1/clusters/{name}/registration-tokens #

List reusable registration tokens (automation)

Parameters

  • name path string required

Responses

200 Registration tokens for this cluster (never the secret).
Response body
  • tokensRegistrationToken[]required
    Show fields
    • idstringrequired
    • namestringrequired
    • createdAtstringrequired
    • expiresAtstring
    • lastUsedstring
    • disabledbooleanrequired
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (quota or org mismatch).
Response body
  • errorstringrequired
404 Unknown cluster.
Response body
  • errorstringrequired
POST /api/v1/clusters/{name}/registration-tokens #

Create a reusable registration token

Parameters

  • name path string required

Request body

  • namestringrequired
  • expiresIninteger

Responses

201 The token, shown once (bake it into your fleet template).
Response body
  • idstringrequired
  • namestringrequired
  • tokenstringrequired
  • cloudConfigstringrequired
  • joinCommandstringrequired
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (quota or org mismatch).
Response body
  • errorstringrequired
404 Unknown cluster.
Response body
  • errorstringrequired
PATCH /api/v1/clusters/{name}/registration-tokens/{id} #

Deactivate or reactivate a registration token

Parameters

  • name path string required
  • id path string required

Request body

  • disabledbooleanrequired

Responses

204 Updated.
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (quota or org mismatch).
Response body
  • errorstringrequired
404 Unknown cluster.
Response body
  • errorstringrequired
DELETE /api/v1/clusters/{name}/registration-tokens/{id} #

Revoke a registration token

Parameters

  • name path string required
  • id path string required

Responses

204 Revoked.
401 Unauthenticated.
Response body
  • errorstringrequired
403 Forbidden (quota or org mismatch).
Response body
  • errorstringrequired
404 Unknown cluster.
Response body
  • errorstringrequired