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

Get a Kubernetes cluster

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.

Required permission

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

Command line

The orl CLI wraps this endpoint:

orl kube cluster get <id>
GET
/v1/kubernetes/clusters/{id}

Authorization

apiKey
headerAuthorizationBearer <token>

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

Path Parameters

id*string

Response Body

The cluster

application/json
  1. response

A managed Kubernetes cluster. We run its control plane; its nodes are whole hosts in one data center. Credentials are never part of it: use createKubernetesClusterToken or getKubernetesKubeconfig.

id*string

Cluster id. It is also the first label of the API server hostname.

Formatuuid
orgId*string
name*string
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"
kubernetesVersion*string

Kubernetes version of the control plane and every node, for example v1.37.1.

locationId*string

The data center the cluster's nodes run in. A cluster never spans data centers.

controlPlane*

The managed control plane. One size, two replicas.

network*
nodeCounts*
conditions?array<>
createdAt*string
updatedAt*string
Example Request
curl -X GET 'https://api.openrelay.inc/v1/kubernetes/clusters/string'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "orgId": "string",  "name": "string",  "status": "creating",  "kubernetesVersion": "string",  "locationId": "string",  "controlPlane": {    "replicas": 0,    "readyReplicas": 0  },  "network": {    "apiEndpoint": "string",    "podCidr": "string",    "serviceCidr": "string"  },  "nodeCounts": {    "total": 0,    "ready": 0,    "notReady": 0,    "pending": 0  },  "conditions": [    {      "type": "string",      "status": "True",      "reason": "string",      "message": "string",      "lastTransitionTime": "string"    }  ],  "createdAt": "string",  "updatedAt": "string"}

Create a Kubernetes cluster POST

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.

Delete a Kubernetes cluster DELETE

Starts deleting the cluster, its node pools and every node, and answers 202; poll getKubernetesCluster, which answers 404 once deletion completes. Deletion is final: the cluster's state is not kept. Repeating the call finishes a deletion that could not remove everything. A legacy API key needs clusters:write.