Create cluster API Reference

POST

/tenants/{tenant}/clusters

Create a new managed Kubernetes cluster. The cluster will be provisioned asynchronously — poll the GET endpoint and check status.phase until it reaches “Running”.

Cluster types:

shared: Cost-effective, runs on shared infrastructure (vCluster). The only supported value today; also the default when type is omitted.
dedicated: Reserved for a future release (isolated compute) — not yet supported; requests with type: 'dedicated' are rejected with a 400.

Resource fields (cpu, memory, storage) use Kubernetes quantity format (e.g., “4”, “500m”, “16Gi”).

Authorizations

BearerAuth

Parameters

Path Parameters

tenant

required

string

Tenant name

Request Body

Cluster configuration

object

alerts

Alert configuration (free-form object)

object

key

additional properties

displayName

Human-readable display name

string

Example

Production Cluster

highAvailability

HighAvailability enables a 3-replica control plane with HA etcd (chart-managed external etcd StatefulSet), anti-affinity, and encrypted-at-rest etcd. Default false. See pricing docs for the hourly rate; charging starts when the operator confirms 3/3 replicas ready (status.haEnabledAt). Create-time-only in v1 — the PATCH endpoint rejects both directions of the toggle.

boolean

Example

true

name

Cluster name (DNS-safe, 2-63 characters)

string

Example

production

resources

Resource allocations using Kubernetes quantity format

object

cpu

string

Example

memory

string

Example

16Gi

storage

string

Example

100Gi

type

Cluster type. Only “shared” is currently accepted; “dedicated” is reserved for a future release.

string

Allowed values: shared

Example

shared

version

Kubernetes version (optional; when omitted the platform default version is used)

string

Example

1.32

Responses

201

Cluster created

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