Update cluster API Reference

PATCH

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

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)

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

memory

string

Example

16Gi

storage

string

Example

100Gi

version

Target Kubernetes version for upgrade

string

Example

1.33

Responses

200

Updated cluster

object

alerts

object

key

additional properties

createdAt

string

Example

2026-02-01T14:00:00Z

displayName

string

Example

Production Cluster

highAvailability

boolean

Example

true

name

string

Example

production

resourceVersion

string

Example

resources

object

cpu

string

Example

memory

string

Example

16Gi

storage

string

Example

100Gi

status

object

conditions

Array<object>

object

key

additional properties

endpoint

string

Example

https://production.acme.clusters.kupe.cloud

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

Example

true

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

Example

2026-05-25T14:32:11Z

haEtcdReplicasDesired

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

integer

Example

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

Example

haPhase

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

string

Example

ha-healthy

haReplicasDesired

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

integer

Example

haReplicasReady

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

integer

Example

kubernetesVersion

string

Example

v1.32.3

metrics

object

key

additional properties

phase

string

Example

Running

type

string

Example

shared

version

string

Example

1.32

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

Example

HA_K8S_VERSION_RETIRING

field

string

Example

spec.highAvailability

message

string

Example

Cluster's Kubernetes version (1.33) is approaching end-of-life on the current vCluster chart. Plan an upgrade before enabling HA.

severity

string

Example

warning

message

string

severity

string