Create a Cluster

This guide walks through creating a managed cluster, understanding the key request fields, and waiting for the cluster to become ready.

For the complete request and response schema, see the Reference: clusters section.

Request

POST /api/v1/tenants/{tenant}/clusters

export KUPE_TENANT="<tenant>"

curl -X POST \
  -H "Authorization: Bearer $KUPE_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.kupe.cloud/api/v1/tenants/$KUPE_TENANT/clusters" \
  -d '{
    "name": "production",
    "displayName": "Production",
    "type": "shared",
    "version": "1.31",
    "resources": {
      "cpu": "4",
      "memory": "16Gi",
      "storage": "100Gi"
    }
  }'

Fields

Field	Required	Mutable	Description
`name`	Yes	No	Unique cluster name.
`displayName`	Yes	No	Human-readable display name.
`type`	Yes	No	`shared` for the standard multi-tenant model, or `dedicated` where that is enabled for your tenant.
`version`	No	Yes	Kubernetes version such as `1.31`.
`resources`	No	Yes	CPU, memory, and storage limits in Kubernetes quantity format (`4`, `16Gi`, `100Gi`).
`alerts`	No	Yes	Alert configuration overrides, if you are already managing them through the API.

Response

201 Created with the cluster object and an ETag header for use with later PATCH requests:

{
  "name": "production",
  "displayName": "Production",
  "type": "shared",
  "version": "1.31",
  "resources": { "cpu": "4", "memory": "16Gi", "storage": "100Gi" },
  "status": { "phase": "Pending" },
  "resourceVersion": "12345",
  "createdAt": "2026-04-06T12:00:00Z"
}

The cluster is provisioned asynchronously — status.phase starts at Pending and progresses through Provisioning to Running.

Wait for the cluster to be ready

Poll the GET endpoint until status.phase reaches Running. The script below has a 15-minute timeout and exits non-zero on failure, making it safe to use in CI:

export KUPE_TENANT="<tenant>"
export KUPE_CLUSTER="production"

TIMEOUT_SECONDS=900   # 15 minutes
INTERVAL=10
ELAPSED=0

while [ "$ELAPSED" -lt "$TIMEOUT_SECONDS" ]; do
  PHASE=$(curl -s \
    -H "Authorization: Bearer $KUPE_API_KEY" \
    "https://api.kupe.cloud/api/v1/tenants/$KUPE_TENANT/clusters/$KUPE_CLUSTER" \
    | jq -r '.status.phase')
  echo "Phase: $PHASE (elapsed ${ELAPSED}s)"

  case "$PHASE" in
    Running)
      echo "Cluster is ready!"
      exit 0
      ;;
    Failed|Error)
      echo "Cluster provisioning failed (phase: $PHASE)" >&2
      exit 1
      ;;
  esac

  sleep "$INTERVAL"
  ELAPSED=$((ELAPSED + INTERVAL))
done

echo "Timed out waiting for cluster after ${TIMEOUT_SECONDS}s" >&2
exit 1

Get connection details

Once the cluster is Running, fetch its API endpoint and CA certificate:

curl -s \
  -H "Authorization: Bearer $KUPE_API_KEY" \
  "https://api.kupe.cloud/api/v1/tenants/$KUPE_TENANT/clusters/$KUPE_CLUSTER/kubeconfig"

This endpoint returns connection details, not a full interactive user kubeconfig blob. See Reference: cluster connection details for the exact response shape.