Skip to content
OpenRelay is in early access, and the /v1 API is stable. New capabilities ship in the changelog.
PricingDashboard
GuidesAPI ReferenceCLI
API ReferenceComputeKubernetes

Create a Kubernetes cluster

Starts creating a cluster with a managed control plane in one data center and answers 202 with its id; 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. A create that meets a concurrent change to the organization answers 409 CONCURRENT_UPDATE; retry it. A legacy API key needs clusters:write.

Required permission

Requires the kubernetes.write permission. See Permissions for the roles and API key permissions that include it.

Command line

The orl CLI wraps this endpoint:

orl kube cluster create --location-id <location-id> --name <name>
POST
/v1/kubernetes/clusters

Authorization

apiKey
headerAuthorizationBearer <token>

OpenRelay API key. Send it as Authorization: Bearer or_… (legacy vl_… keys still work).

Request Body

application/json
  1. body
name*string
Match^[a-z]([a-z0-9-]*[a-z0-9])?$
Length1 <= length <= 63
locationId*string

The data center for the cluster's nodes, one of listLocations.

kubernetesVersion?"v1.37.1"

Kubernetes version. v1.37.1 is the only supported version, and a cluster is not upgraded in place.

Default"v1.37.1"
Value in"v1.37.1"
nodePools?array<>

Node pools to add once the control plane is ready, each as createKubernetesNodePool takes it.

Itemsitems <= 10

Response Body

Creation started

application/json
  1. response

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
Formatuuid
status*KubernetesClusterStatus

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.

Value in"creating""ready""updating""degraded""deleting""failed"
Example Request
curl -X POST 'https://api.openrelay.inc/v1/kubernetes/clusters' \  -H 'Content-Type: application/json' \  -d '{  "name": "string",  "locationId": "string"}'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "status": "creating"}

List Kubernetes clusters GET

The organization's managed Kubernetes clusters, newest first, in cursor pages of summaries with each cluster's status, health, and node and Ready counts. A legacy API key needs clusters:read.

Get a Kubernetes cluster GET

Returns one cluster: its status, Kubernetes version, data center, control-plane replicas, API endpoint, pod and service networks, node counts and conditions. A legacy API key needs clusters:read.