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": {}, "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.

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

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

boolean

haPhase

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

string

kubernetesVersion

string

metrics

object

key

additional properties

phase

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,
    "haPhase": "ha-healthy",
    "kubernetesVersion": "v1.32.3",
    "phase": "Running"
  },
  "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 this platform. Plan an upgrade before enabling high availability.",
      "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"
}

409

The cluster is being deleted (code terminating); a change that grows it while the tenant is suspended, awaiting a payment method or being deleted (codes tenant_suspended, payment_setup_required, tenant_terminating); or the cluster kept changing while it was being updated

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