---
title: "Create a Kubernetes cluster"
method: POST
path: "/v1/kubernetes/clusters"
tags: ["Kubernetes"]
---

# Create a Kubernetes cluster

`POST /v1/kubernetes/clusters`

Starts creating a cluster with a managed control plane in one data center; poll getKubernetesCluster for its status. Node pools in the request are added once the control plane is ready; add more later with createKubernetesNodePool. A cluster's name is unique within the organization: a create with the name of one of its clusters answers 409 NAME_TAKEN until that cluster's deletion completes. An organization has a configured limit on clusters creating at once; a create at that limit answers 409 TOO_MANY_CLUSTERS_CREATING until one of them leaves creating. Needs clusters:write on an API key, or the owner, admin or member role on a session.

## Request body

- CreateKubernetesClusterRequest
  - `kubernetesVersion` 'v1.37.1' — Kubernetes version. v1.37.1 is the only supported version, and a cluster is not upgraded in place.
  - `locationId` string, required — The data center for the cluster's nodes, one of listLocations.
  - `name` string, required
  - `nodePools` CreateKubernetesNodePoolRequest[] — Node pools to add once the control plane is ready, each as createKubernetesNodePool takes it.
    - `count` integer, required — Number of whole-host nodes.
    - `name` string, required
    - `sku` KubernetesNodePoolSku, required — What every node in a pool is: exactly one of gpuModelId or cpuSku. Nodes are whole hosts, so a GPU node is a host of that model with every GPU passed through to it, and a CPU node is a whole CPU host. A cluster mixes SKUs through several pools.
      - `cpuSku` string — Whole-host CPU SKU.
      - `gpuModelId` string — GPU model, one of listGpuModels.

## Response `202`

Creation started

- KubernetesClusterAccepted — A cluster create or delete was accepted: the cluster's id and its status, creating or deleting. Poll getKubernetesCluster, which answers 404 once a deletion completes.
  - `id` string, uuid, required
  - `status` 'creating' | 'ready' | 'updating' | 'degraded' | 'deleting' | 'failed', required — creating: the control plane is being provisioned, and stays creating until it is serving and authorizes the platform's own writes. ready: fully operational. updating: a control-plane change is in progress. degraded: partially operational, for example the control plane stopped serving or its datastore is write-limited. deleting: deletion is in progress and final. failed: an unrecoverable error.

## Other responses

- `400` — The request is invalid
- `401` — Missing or invalid API key
- `403` — The caller is authenticated but may not do this. As on every operation, the caller's role or the API key's scope does not allow it, or the request targets another organization (FORBIDDEN, or NOT_A_MEMBER for a session), or the organization is suspended pending review (ORG_SUSPENDED) or has been deleted (ORG_DISABLED). This operation can also be refused because of the account. A new workload (a VM or pod create, a VM fork, a Kubernetes cluster or node pool create, a node pool scaled up) answers INSUFFICIENT_BALANCE, ACCOUNT_RESTRICTED or ACCOUNT_PENDING_VERIFICATION; a restart or reboot answers INSUFFICIENT_BALANCE; an API key create answers ACCOUNT_RESTRICTED or ACCOUNT_PENDING_VERIFICATION; a deposit or card save answers ACCOUNT_PENDING_VERIFICATION, VERIFICATION_UNAVAILABLE or FUNDING_UNDER_REVIEW; and a runner pool create answers ACCOUNT_PENDING_VERIFICATION. Every gate also answers ACCOUNT_SUSPENDED for a suspended organization, but only platform admins and internal callers reach it: a customer's request for a suspended organization is refused at authentication with ORG_SUSPENDED before it gets to a gate. A new API key or a wider scope clears none of these; see [Account and balance refusals](https://docs.openrelay.inc/docs/errors#account-and-balance-refusals) for what each one means and what to do.
- `404` — Resource not found
- `409` — The request conflicts with existing state

## Changes

- **2026-10-03** `bcf63adad2c3` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/openrelay/apis/openrelay-api/changes/v1/kubernetes/clusters/post.md)

---

[API](https://skmtc.dev/openrelay/apis/openrelay-api.md) · [All operations](https://skmtc.dev/openrelay/apis/openrelay-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openrelay/apis/openrelay-api/revisions/bcf63adad2c3?raw)