curl --request POST \
--url https://api.ornn.com/v1/orchestrator/controllers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"kind": "kubernetes",
"reservation_id": "11111111-1111-4111-8111-111111111111",
"network_mode": "public",
"node_ids": [
"33333333-3333-4333-8333-333333333333"
]
}
'{
"id": "44444444-4444-4444-8444-444444444444",
"kind": "kubernetes",
"organization_id": "22222222-2222-4222-8222-222222222222",
"access_mode": "kubernetes",
"state": "provisioning",
"network_mode": "public",
"endpoint": null,
"credential_state": "pending",
"namespace": "k8s-22222222-2222-4222-8222-222222222222",
"node_count": 0,
"gpu_count": 0,
"progress": null,
"created_at": "2026-10-14T12:00:00Z",
"updated_at": "2026-10-14T12:00:00Z"
}Create a cluster
Launches a Kubernetes or Slurm cluster on capacity your organization already holds; it does not purchase GPUs. List the hosts to use in node_ids. Each must be in bare-metal status, not in another cluster, and on an active reservation your organization owns; hosts can come from more than one such reservation. If node_ids and virtual_machine_ids are both omitted or empty, every bare-metal host on reservation_id is used. Before a host joins, Ornn prepares it - running processes are stopped, the tenant home directory is wiped, and any VM on that host is removed - so save its data first.
Your organization can run one cluster of each kind at a time, and cannot run Kubernetes and Slurm clusters at the same time. A cluster counts until its teardown finishes. A repeat request for a reservation whose cluster is active, or provisioning with workers attached, returns that cluster with 202 and changes nothing, even if the node list differs; change membership with the worker operations. A request after a failed launch on the same reservation relaunches it under the same id. Do not create while a teardown is in progress.
A 202 response means the launch was accepted, not that the cluster is ready. Poll listClusters until state is active or failed, then call getClusterAccess. This route does not read an Idempotency-Key header; after a timeout or 5xx, list clusters and look for the reservation before sending the request again. Unknown body fields are rejected. Malformed JSON, unknown fields, or a missing Content-Type return 400, 422, or 415 with a plain-text body.
curl --request POST \
--url https://api.ornn.com/v1/orchestrator/controllers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"kind": "kubernetes",
"reservation_id": "11111111-1111-4111-8111-111111111111",
"network_mode": "public",
"node_ids": [
"33333333-3333-4333-8333-333333333333"
]
}
'{
"id": "44444444-4444-4444-8444-444444444444",
"kind": "kubernetes",
"organization_id": "22222222-2222-4222-8222-222222222222",
"access_mode": "kubernetes",
"state": "provisioning",
"network_mode": "public",
"endpoint": null,
"credential_state": "pending",
"namespace": "k8s-22222222-2222-4222-8222-222222222222",
"node_count": 0,
"gpu_count": 0,
"progress": null,
"created_at": "2026-10-14T12:00:00Z",
"updated_at": "2026-10-14T12:00:00Z"
}ornn login:
ornn launch --mode kubernetes --reservation RESERVATION_ID --nodes 1 \
--machines NODE_ID --network public
Authorizations
Create an organization API key in Account Settings > Developer. Do not send this key to the Kubernetes API server.
Body
The cluster type to launch.
kubernetes, slurm An active reservation your organization holds. A repeat request for the same reservation returns the same cluster. Use reservationId from the reservation list, not a listing ID.
public exposes the Kubernetes API or Slurm SSH login on the internet, with authentication. private requires a WireGuard connection to your organization's private network.
public, private An existing organization network for private access. Used only when network_mode is private. Omit it to use the shared default network; this does not create a network.
Host IDs (node_id from the reservation node list), not GPU IDs. Each host must be in bare-metal status, not in another cluster, and on an active reservation your organization owns. Ornn prepares each host before it joins, which stops its processes, wipes the tenant home directory, and removes any VM on it. If this and virtual_machine_ids are both omitted or empty, every bare-metal host on reservation_id is used.
Existing VMs on reservations your organization owns to use as workers. A VM must not be deleted, destroyed, or offline. Do not list a VM and its host in node_ids in the same request.
Optional expected host count; it never selects or limits hosts. Kubernetes ignores it. Slurm rejects the launch with 409 cluster_nodes_requested_unavailable when it differs from the number of hosts that resolved. Omit it, or send exactly the number of hosts you list.
Slurm only. Organization SSH key IDs (ssh_keys[].id from GET /v1/organizations/{organization_id}/ssh-keys) to authorize on the login node. Omit to authorize every active key in your organization; with no active key, Slurm launch returns 409 slurm_ssh_key_required. Kubernetes ignores this field.
Accepted for compatibility and ignored.
Response
Launch accepted. node_count and gpu_count count workers attached so far and are usually 0 in this response. Poll listClusters for progress.
The namespace Ornn configures for your workloads.
Workers attached when this response was built; usually 0 right after a launch.
GPUs on the workers counted in node_count.
Stages of the latest launch or teardown. Launch stages are create_plane, prepare_hosts, join_workers, apply_plane, and issue_access. Teardown stages include workers and the control-plane stage (namespace for Kubernetes, stack for Slurm), plus nodes or storage when those steps fail.
Show child attributes
Show child attributes
Was this page helpful?