Create cluster API Reference
const url = 'https://api.kupe.cloud/api/v1/tenants/acme/clusters';const options = { method: 'POST', headers: {Authorization: '<Authorization>', 'Content-Type': 'application/json'}, body: '{"alerts":{"additionalProperty":"example"},"displayName":"Production Cluster","highAvailability":true,"name":"production","resources":{"cpu":"4","memory":"16Gi","storage":"100Gi"},"type":"shared","version":"1.32"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.kupe.cloud/api/v1/tenants/acme/clusters \ --header 'Authorization: <Authorization>' \ --header 'Content-Type: application/json' \ --data '{ "alerts": { "additionalProperty": "example" }, "displayName": "Production Cluster", "highAvailability": true, "name": "production", "resources": { "cpu": "4", "memory": "16Gi", "storage": "100Gi" }, "type": "shared", "version": "1.32" }'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
typeis 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
Section titled “ Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “ Path Parameters ”Tenant name
Request Body
Section titled “ Request Body ”Cluster configuration
object
Alert configuration (free-form object)
object
Deprecated: accepted for backward compatibility and ignored (the cluster name is the identifier).
Example
Production ClusterHighAvailability 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.
Example
trueCluster name (DNS-safe, 2-63 characters)
Example
productionResource allocations using Kubernetes quantity format
object
Example
4Example
16GiExample
100GiCluster type. Only “shared” is currently accepted; “dedicated” is reserved for a future release.
Example
sharedKubernetes version (optional; when omitted the platform default version is used)
Example
1.32Responses
Section titled “ Responses ”Cluster created
object
object
Deprecated: always equal to name (the CRD has no display name; the cluster name is the identifier).
object
object
object
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.
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).
HAEtcdReplicasDesired is the target HA etcd replica count (3 when HA is enabled, 0 otherwise).
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.
HAPhase is the consumer-friendly HA rollup. One of pending, ha-healthy, ha-degraded, ha-unavailable. Empty for non-HA clusters.
HAReplicasDesired is the target HA replica count (3 when HA is enabled, 0 otherwise).
HAReplicasReady is the count of HA control-plane (apiserver) replicas currently Ready.
object
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.
object
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
Section titled “ Headers ”Resource version
Validation error
object
Example generated
{ "code": "example", "error": "example", "field": "example", "message": "example", "severity": "example"}Missing or invalid authentication
object
Example generated
{ "code": "example", "error": "example", "field": "example", "message": "example", "severity": "example"}Admin access required
object
Example generated
{ "code": "example", "error": "example", "field": "example", "message": "example", "severity": "example"}Cluster name already exists
object
Example generated
{ "code": "example", "error": "example", "field": "example", "message": "example", "severity": "example"}Rate limit exceeded
object
Example generated
{ "code": "example", "error": "example", "field": "example", "message": "example", "severity": "example"}