List clusters API Reference

GET

/tenants/{tenant}/clusters

curl --request GET \
  --url https://api.kupe.cloud/api/v1/tenants/acme/clusters \
  --header 'Authorization: <Authorization>'

List all managed Kubernetes clusters belonging to the tenant. Returns cluster metadata, resource allocations, and current status for each cluster.

Authorizations

• BearerAuth

Parameters

Path Parameters

tenant

required

string

Tenant name

Responses

200

List of clusters

Media type application/json

object

items

Array<object>

object

alerts

object

key

additional properties

createdAt

string

displayName

Deprecated: always equal to name (the CRD has no display name; the cluster name is the identifier).

string

highAvailability

boolean

name

string

resourceVersion

string

resources

object

cpu

string

memory

string

storage

string

status

object

conditions

Array<object>

object

key

additional properties

endpoint

string

haConfigured

HAConfigured is true once the operator has confirmed both 3/3 apiserver replicas AND 3/3 deployed-etcd replicas are Ready for the first time. Etcd readiness is required because in the OSS deployed-etcd path etcd runs in its own StatefulSet — quorum loss with healthy apiserver pods would block writes, so HA is not “operationally ready” until both tiers report 3/3.

boolean

haEnabledAt

HAEnabledAt is the moment HAConfigured first became true and acts as the billing anchor. Stamped once, never updated, never cleared (v1 has no HA->single transition).

string

haEtcdReplicasDesired

HAEtcdReplicasDesired is the target HA etcd replica count (3 when HA is enabled, 0 otherwise).

integer

haEtcdReplicasReady

HAEtcdReplicasReady is the count of deployed-etcd replicas currently Ready. Exposed separately from HAReplicasReady because in the OSS deployed-etcd path the etcd StatefulSet is independent of the apiserver StatefulSet, and etcd quorum loss with healthy CP can leave the cluster unable to serve writes.

integer

haPhase

HAPhase is the consumer-friendly HA rollup. One of pending, ha-healthy, ha-degraded, ha-unavailable. Empty for non-HA clusters.

string

haReplicasDesired

HAReplicasDesired is the target HA replica count (3 when HA is enabled, 0 otherwise).

integer

haReplicasReady

HAReplicasReady is the count of HA control-plane (apiserver) replicas currently Ready.

integer

kubernetesVersion

string

metrics

object

key

additional properties

phase

string

type

string

version

string

warnings

Warnings is an array of structured advisory messages. Always present (empty array when none). Populated today only by CREATE when a non-blocking advisory applies (e.g. HA_K8S_VERSION_RETIRING when HA is enabled on the oldest supported k8s minor). Each entry shares the same shape as a structured error envelope.

Array<object>

object

code

string

field

string

message

string

severity

string

Example

{
  "items": [
    {
      "createdAt": "2026-02-01T14:00:00Z",
      "displayName": "production",
      "highAvailability": true,
      "name": "production",
      "resourceVersion": "294810",
      "resources": {
        "cpu": "4",
        "memory": "16Gi",
        "storage": "100Gi"
      },
      "status": {
        "endpoint": "https://production.acme.clusters.kupe.cloud",
        "haConfigured": true,
        "haEnabledAt": "2026-05-25T14:32:11Z",
        "haEtcdReplicasDesired": 3,
        "haEtcdReplicasReady": 3,
        "haPhase": "ha-healthy",
        "haReplicasDesired": 3,
        "haReplicasReady": 3,
        "kubernetesVersion": "v1.32.3",
        "phase": "Running"
      },
      "type": "shared",
      "version": "1.32",
      "warnings": [
        {
          "code": "HA_K8S_VERSION_RETIRING",
          "field": "spec.highAvailability",
          "message": "Cluster's Kubernetes version (1.33) is approaching end-of-life on the current vCluster chart. Plan an upgrade before enabling HA.",
          "severity": "warning"
        }
      ]
    }
  ]
}

400

Invalid tenant name

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

401

Missing or invalid authentication

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

403

Not a member of this tenant

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

429

Rate limit exceeded

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}