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

Update a node pool

Replaces supplied public ports, labels, annotations, and taints; omitted fields stay unchanged. Returns the pool with HTTP 202. Each node's host applies the new list within about a minute, and a removed port cuts the connections it carries. Each node takes the new labels, annotations, and taints within about a minute. A pool taint it drops is removed from its nodes, while taints set by others are preserved unless they use the same key and effect as a desired pool taint. A body that changes nothing answers 202 and writes nothing. A cluster that is deleting answers 409 INVALID_CLUSTER_STATE, a pool that is deleting 409 INVALID_NODE_POOL_STATE, and a list with a refused port, an overlap or too many sources 400 INVALID_PUBLIC_PORTS. A taint schema violation, including an unknown effect, a key over 317 characters, a value over 63 characters, more than 32 taints or an unknown field, answers 400 BAD_REQUEST. Invalid taint key or value syntax, a reserved key, or a repeated key and effect pair answers 400 INVALID_NODE_METADATA naming its entry. A refused label or annotation also answers 400 INVALID_NODE_METADATA. 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 kubernetes node-pool update <id> <pool-id>
PATCH
/v1/kubernetes/clusters/{id}/node-pools/{poolId}

Authorization

apiKey
headerAuthorizationBearer <token>

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

Path Parameters

id*string
poolId*string

Request Body

application/json
  1. body
Properties1 <= properties
publicPorts?array<>

The pool's new public ports, replacing the list it holds; an empty list forwards no port. Absent leaves the list as it is. Each node's public IP follows within about a minute, without restarting the node, and a removed port cuts the connections it carries.

Itemsitems <= 32
labels?

The pool's new labels, replacing the ones it holds; an empty map removes them. Absent leaves them as they are. Each of the pool's nodes follows within about a minute. A key the pool drops is removed from its nodes unless something else, such as kubectl, last set it.

Propertiesproperties <= 64
annotations?

The pool's new annotations, replacing the ones it holds, as labels does.

Propertiesproperties <= 64
taints?array<>

The pool's new taints, replacing the ones it holds. An empty list clears them, and an absent field leaves them unchanged. Each node follows within about a minute. A taint the pool drops is removed from its nodes; taints set by others are preserved unless they use the same key and effect as a desired pool taint.

Itemsitems <= 32
expectedPublicPorts?array<>

Optional list the caller reviewed, compared with the pool's list as a set. If they differ, answers 409 CONCURRENT_UPDATE without changing anything, so a change made since the review is not undone. The comparison and write are atomic.

Itemsitems <= 32

Response Body

Update accepted

application/json
  1. response

A set of identical nodes in one cluster.

id*string
clusterId*string
name*string
sku*

What every node in a pool is: exactly one of gpuModelId or resourceSize. A GPU node is a whole host of that model with every GPU passed through to it. A CPU node is a VM of that size alone on a host that sells no GPU, billed as a CPU VM of the size; the rest of the host is left unused. A cluster mixes SKUs through several pools.

Properties1 <= properties <= 1
diskSizeGb?integer

A CPU pool's data disk per node, in GB, beside the node's 100 GB root disk. Absent on a GPU pool, whose nodes take their host's free disk.

count*integer

Nodes the pool holds once it converges.

readyCount*integer

Nodes that joined the cluster and are Ready.

status*string
Value in"creating""ready""scaling""deleting""failed"
publicPorts*array<>

The ports each node's public IP forwards to the node, empty when none does. Every other port on the node's public IP answers nothing.

Itemsitems <= 32
labels*

The labels on each of the pool's nodes, empty when the pool sets none.

Propertiesproperties <= 64
annotations*

The annotations on each of the pool's nodes, empty when the pool sets none.

Propertiesproperties <= 64
taints*array<>

The taints on each of the pool's nodes, empty when the pool sets none.

Itemsitems <= 32
conditions?array<>

The conditions that hold on the pool, each while it holds: why the pool is short of its count, for example WaitingForCapacity (reason NoEligibleHost: no host in the cluster's data center has room for another node of the pool) or CreateRefused (the organization cannot add nodes now, for example its balance), and PublicPortsPending (reason HostsNotApplied) while some of its nodes have not applied its public ports. Absent while none holds.

createdAt*string
Example Request
curl -X PATCH 'https://api.openrelay.inc/v1/kubernetes/clusters/string/node-pools/string' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "id": "string",  "clusterId": "string",  "name": "string",  "sku": {    "gpuModelId": "string"  },  "diskSizeGb": 0,  "count": 0,  "readyCount": 0,  "status": "creating",  "publicPorts": [    {      "protocol": "tcp",      "port": 1,      "endPort": 1,      "sources": [        "string"      ]    }  ],  "labels": {    "property1": "string",    "property2": "string"  },  "annotations": {    "property1": "string",    "property2": "string"  },  "taints": [    {      "key": "string",      "value": "string",      "effect": "NoSchedule"    }  ],  "conditions": [    {      "type": "string",      "status": "True",      "reason": "string",      "message": "string",      "lastTransitionTime": "string"    }  ],  "createdAt": "string"}