Cluster lifecycle¶

This page is the create → read → follow progress → update metadata → delete loop on /v1/public/clusters. Node pools, kubeconfig, Elastic IPs, and firewall rules have their own pages; they all require Provisioned except kubeconfig (also allowed at ControlPlaneReady) and cluster delete (any phase).

Who can do this: member can list, get, and long-poll. super_admin can create, patch, change exposure, and delete.

Create¶

POST /v1/public/clusters → 201 and a PublicClusterResponse with phase=Requested. Provisioning continues asynchronously.

Console: https://door.cloud/dks/clusters/new. On success the UI opens /dks/clusters/<id>/provisioning.

Maya: “Create cluster payments-prod in Abidjan with two dks.c5.xlarge workers.” Approve the confirmation card.

PublicClusterCreateRequest¶

extra="forbid": unknown keys (including any control-plane field) → 422.

There is no control-plane field. Door applies the control plane assigned to your organization. The zone's active catalog option is the default.

node_pools[] (PublicNodePoolRequest)¶

Autoscaling validation errors are 422 (create body) or 422 on later PATCH.

curl -sS -X POST "https://dks-api.apps.door.cloud/v1/public/clusters" \
  -H "Authorization: Bearer $DOOR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f3a0c11-create-payments" \
  -d '{
    "name": "payments-prod",
    "organization": "acme",
    "zone": "abidjan",
    "kubernetes_version": "v1.32.4",
    "exposure_mode": "public",
    "node_pools": [
      { "name": "workers", "size": "dks.c5.xlarge", "count": 2 }
    ],
    "tags": ["frontend"],
    "description": "Payments production"
  }'

Idempotency-Key¶

Optional header on create and on cluster delete (and on pool PATCH).

Use a new key per distinct create (for example a UUID).

Create status codes¶

Read¶

List¶

GET /v1/public/clusters

There is no phase query filter on this public list. Filter client-side on items[].phase.

curl -sS "https://dks-api.apps.door.cloud/v1/public/clusters?zone=abidjan&page=1&size=20" \
  -H "Authorization: Bearer $DOOR_TOKEN" \
  -H "X-Door-Organization: acme"

Envelope: items, total, page, size, total_pages.

Console: https://door.cloud/dks/clusters.

Maya: “List my clusters in Abidjan.”

Get one¶

GET /v1/public/clusters/{id} → PublicClusterResponse. Organization comes from the row (403 if you are not a member of that org, 404 if the id does not exist).

PublicClusterResponse fields¶

Follow progress¶

GET /v1/public/clusters/{id}/state

Response header X-State-Version equals state_version. If no snapshot exists yet: 404 no projected state for cluster … — retry GET the cluster or /state shortly after create.

Body (PublicClusterStatusResponse):

progress.step is present on the create path (5 steps). It is null for Failed / Deleting / Deleted (except a failed create may still show step 3 Creating infrastructure when that is known).

Create steps (titles and messages)¶

Render title and message from the API. They are:

Deleting: title Deleting, message Removing your cluster's resources. This can take a few minutes. (percent null). Deleted: title Deleted, message Cluster removed. (percent 100). Failed: title Setup failed, message from the failure list below.

curl -sS \
  "https://dks-api.apps.door.cloud/v1/public/clusters/${CLUSTER_ID}/state?since=0&timeout_seconds=25" \
  -H "Authorization: Bearer $DOOR_TOKEN"

Console: /dks/clusters/<id>/provisioning. Maya: progress card after you approve create.

Update metadata¶

PATCH /v1/public/clusters/{id} → 200. Only tags and/or description. Omitted keys stay unchanged. description: null clears it. name is not accepted (immutable). Empty body → 422. Soft-deleted cluster → 409.

curl -sS -X PATCH \
  "https://dks-api.apps.door.cloud/v1/public/clusters/${CLUSTER_ID}" \
  -H "Authorization: Bearer $DOOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["frontend", "prod"], "description": "Payments production" }'

To flip API exposure: PATCH /v1/public/clusters/{id}/exposure with { "exposure_mode": "public" } or "private" → 202. Then re-download kubeconfig. Transient 409 means a previous change is still applying — retry. 400 if public exposure is not available for the zone.

Console: tags/description on Overview / Settings; exposure on Access & kubeconfig. Maya: “Set description on payments-prod to Payments production.”

Delete¶

DELETE /v1/public/clusters/{id} → 202, phase=Deleting. Idempotent: repeating delete while already Deleting does not start a second teardown (unless a failed delete needs a retry).

curl -sS -X DELETE \
  "https://dks-api.apps.door.cloud/v1/public/clusters/${CLUSTER_ID}" \
  -H "Authorization: Bearer $DOOR_TOKEN" \
  -H "Idempotency-Key: payments-prod-delete-001"

Then poll /state until Deleted. GET the id eventually returns 404. Treat that 404 as success.

What is removed with the cluster: node pools, worker nodes, Elastic IPs, and firewall rules attached to it. You do not delete those first. Workloads on the cluster are destroyed with it.

Console: Settings → delete. Maya: “Delete cluster payments-prod.” Approve.

Failed clusters¶

When phase=Failed, failure_message is one of:

There is no "retry create" verb. Delete the failed cluster, then POST again (new Idempotency-Key). A failed delete stays in Deleting with a mapped failure_message — call DELETE again after support has cleared the blockage.

Next¶

• Node pools once Provisioned
• Kubeconfig from ControlPlaneReady or Provisioned