Update cluster API Reference

PATCH

/tenants/{tenant}/clusters/{name}

curl --request PATCH \
  --url https://api.kupe.cloud/api/v1/tenants/acme/clusters/production \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --header 'If-Match: 294810' \
  --data '{ "alerts": { "additionalProperty": "example" }, "highAvailability": true, "resources": { "cpu": "4", "memory": "16Gi", "storage": "100Gi" }, "version": "1.33" }'

Update mutable fields on a managed cluster. At least one field must be provided.

Changing version triggers a rolling Kubernetes upgrade. Changing resources adjusts the resource allocation for the cluster. Both operations are applied asynchronously.

Authorizations

• BearerAuth

Parameters

Path Parameters

tenant

required

string

Tenant name

name

required

string

Cluster name

Header Parameters

If-Match

string

ETag for optimistic locking

Request Body

Fields to update (at least one required)

Media type application/json

object

alerts

Updated alert configuration

object

key

additional properties

highAvailability

HighAvailability is a create-time-only setting in v1. Both directions of the toggle are rejected on PATCH: false -> true is rejected with HA_ENABLE_ON_EXISTING_UNSUPPORTED; true -> false is rejected with HA_DISABLE_UNSUPPORTED. Tenants who want HA on an existing cluster recreate it as HA (blue-green swap).

boolean

Example

true

resources

Updated resource allocations

object

cpu

string

Example

4

memory

string

Example

16Gi

storage

string

Example

100Gi

version

Target Kubernetes version for upgrade

string

Example

1.33

Responses

200

Updated cluster

Media type application/json

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

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

Headers

ETag

string

New resource version

400

Validation error

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

Admin access required

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

404

Cluster not found

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

412

ETag mismatch

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