What DKS is¶

DKS (Door Kubernetes Service) gives your organization a managed Kubernetes cluster for each create request. You choose the zone, Kubernetes version, worker size, and how the API is reached. Door runs the control plane. You run workloads with kubectl once you have a kubeconfig.

This page introduces the objects you will see, the three ways to manage clusters, the lifecycle phases, and the split between what you manage and what Door manages.

Who can do this: member can list and read clusters. super_admin can create, update, scale, and delete. See Authentication and organizations.

Concepts¶

The control plane is not a concept you configure. Public create has no control-plane field. Extra fields such as a control-plane profile are rejected with 422.

A cluster also reports hub registration (whether the cluster is registered with the Door hub: pending, registered, or failed) and a default environment (pending, ready, or failed). Those are status fields, not create options.

Organization (acme)
  └── Zone (abidjan)
        └── Cluster (payments-prod)
              ├── Node pools → nodes
              ├── Elastic IPs
              └── Firewall rules
        Exposure: public | private          (Kubernetes API)
        Network mode: intranet | internet   (application dataplane; set at create)

Examples in this set: organization acme, zone abidjan, cluster payments-prod, id 3f9c1a2e-7b4d-4c58-9e21-5d6f8a0b1c2d, pool workers, machine tier dks.c5.xlarge, Kubernetes v1.32.4. Auth: Authorization: Bearer $DOOR_TOKEN.

Three management channels, plus kubectl¶

You can do the same cluster operations through:

1. Door console — https://door.cloud/dks/clusters. Create wizard at /dks/clusters/new. After create, /dks/clusters/<id>/provisioning follows setup. Cluster detail tabs: Overview, Nodes, Networking, Access & kubeconfig, Settings.
2. REST API — https://dks-api.apps.door.cloud. Customer routes are /v1/public/clusters... and /v1/catalog only. Every route, header, status code, and schema is in the API reference.
3. Maya — the Door AI assistant in the console. Ask in natural language. Maya pauses for your approval before it creates, scales, or deletes. After you approve, a progress card follows the same progress block as the API.

After you download a kubeconfig, kubectl (and any Kubernetes client) talks to your cluster, not to the DKS API. RBAC inside the cluster is yours. See Kubeconfig and kubectl.

Pick the channel that fits the task. The console is fastest for a first cluster. The API is for automation (Idempotency-Key, long-poll /state). Maya is for conversational create/scale/delete with an approval step. Read-only Maya questions (list, catalog, status) do not need approval.

Cluster lifecycle¶

Create walks through five public phases, then you operate the cluster at Provisioned. Teardown is Deleting then Deleted. Setup can fail at any time before Provisioned.

flowchart LR
  Requested --> Provisioning
  Provisioning --> ControlPlaneReady
  ControlPlaneReady --> NodesReady
  NodesReady --> Provisioned
  Requested -.-> Failed
  Provisioning -.-> Failed
  ControlPlaneReady -.-> Failed
  NodesReady -.-> Failed
  Provisioned --> Deleting
  Failed --> Deleting
  Deleting --> Deleted

Requested → Provisioning → ControlPlaneReady → NodesReady → Provisioned
                ↘              ↘                   ↘              ↘ Failed
Provisioned or Failed → Deleting → Deleted → (GET returns 404)

Gating (409)¶

These public writes and reads check phase=Provisioned and return 409 otherwise:

• Add / scale / remove a node pool
• Allocate / release an Elastic IP
• Create / delete a firewall rule
• List nodes (GET …/nodes and GET …/node-pools/{pool}/nodes) — detail cluster not ready yet
• Delete a single node

Kubeconfig is the exception: it is allowed at ControlPlaneReady or Provisioned. Cluster delete is allowed in any phase, including Failed and still-provisioning.

Scale and similar work do not change phase. While workers are added, phase stays Provisioned and GET …/state lists the activity under operations[].

Follow progress with GET /v1/public/clusters/{id} or long-poll GET /v1/public/clusters/{id}/state?since=<state_version>&timeout_seconds=25 (max 60; header X-State-Version). The console Provisioning page and Maya's progress card use the same progress block (title, message, percent, step). 202 on a mutation means accepted — poll /state or re-GET the cluster; do not assume the workers exist yet. Create itself returns 201 and then the same progress path.

Failed setup does not block the name forever after you delete. After Deleted / 404, you may create payments-prod again with a new Idempotency-Key.

What you manage vs what Door manages¶

You never send provider size names, image names, or control-plane knobs. Unknown machine tiers return 400 listing only public tier ids. There is no public route to change kubernetes_version after create.

Exposure vs Elastic IP vs firewall:

• Exposure is the Kubernetes API hostname (kubectl).
• Elastic IP is an address for your applications (a Service or Ingress you attach later).
• Firewall rule opens ports on workers regardless of whether you allocated an Elastic IP.

Deleting the cluster removes pools, Elastic IPs, and firewall rules with it.

Pricing, pager, and SLA numbers are not published here. Contact your Door account team. Catalog pricing may be present for a zone; when it is null, ask that team.

Public routes (map)¶

Base URL: https://dks-api.apps.door.cloud. Auth: Authorization: Bearer $DOOR_TOKEN.

Next steps¶

• Get a first cluster running (~15 minutes)
• Authenticate and pick an organization
• Read the catalog before you create
• Cluster create, read, progress, update, delete
• Node pools and nodes
• Kubeconfig and kubectl
• API server exposure
• Elastic IPs
• Firewall rules
• Door console
• Maya AI assistant
• Errors and troubleshooting
• Limits and constraints
• API reference

The guide index and glossary are on Start here: Door Kubernetes Service.