Docs
Clusters

Add a node pool

POST
/v1/clusters/{id}/node-pools

Adds a pool of nodes to the cluster, and returns it provisioning. Requires Idempotency-Key. Its nodes are instances that Cluster API creates, replaces and deletes; change them through the pool.

Authorization

headerAuthorizationBearer <cc_...>

An API key of your org, sent as Authorization: Bearer cc_.... Keys start with cc_ and are otherwise opaque. Treat a key as a password: anyone holding it can act with its scopes until it expires or is revoked. Each operation's security requirement lists the scopes it needs; an empty list means any valid key. The MCP server at /mcp accepts agent keys and no other kind.

Scope: clusters:write

Path Parameters

id*string

The cluster id.

Match^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length1 <= length <= 63

Header Parameters

Idempotency-Key*string

A unique key for this intent, such as a UUID. Reuse it for every retry of the same request. A missing key returns 400 idempotency_key_required. See Idempotency above.

Match^[!-~]+$
Length1 <= length <= 255
Api-Version*string

The API version the request is written against. This document describes 2026-10-15. A missing header returns 400 api_version_required, and a version the API does not serve returns 400 unsupported_api_version.

X-Correlation-ID?string

An id of your own for this request, or for a group of requests, to find them in our logs and yours. Logged with the request and returned unchanged in X-Correlation-ID. The request id itself is always the API's own, in X-Request-ID.

Match^[A-Za-z0-9._:-]+$
Length1 <= length <= 128
Org-Context?string

Admin keys only: the id of the org to act in. Required with an admin key, together with Access-Reason; with any other credential it returns 400 invalid_request. Every request that carries it is recorded in that org's operator-access log.

Match^org-[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length5 <= length <= 63
Access-Reason?string

Admin keys only: why the operator is acting in the org, such as a support ticket. Required with Org-Context. Recorded, verbatim, in the org's operator-access log.

Match^[^\x00-\x1F\x7F]+$
Length10 <= length <= 500

Request Body

application/json
  1. body

A pool of nodes, which Cluster API runs as a MachineDeployment. Set exactly one of replicas and autoscaling.

name*NodePoolName

A lowercase DNS label, unique among the cluster's live pools. control-plane is reserved.

Match^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length1 <= length <= 40
location?LocationId

Where the pool's nodes run, the cluster's location without it. A pool runs in the cluster's location, or at one of its satellites (satelliteOf on GET /v1/locations) whose subnet the cluster's uploaded launch file names (launchInputs.nodeCidrs). A pool at a satellite takes a GPU size and a reservation there. Any other location is 422 unsupported_combination, with violation incompatible at the pool's location.

Match^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length1 <= length <= 63
size*SizeId

A size the worker image the pool's nodes boot runs, which nodePool marks in GET /v1/sizes; another is 422 unsupported_combination, with violation incompatible at the pool's size. A GPU size needs reservation.

Match^[a-z0-9]([-.a-z0-9]*[a-z0-9])?$
Length1 <= length <= 63
replicas?integer

How many nodes to run.

Range0 <= value <= 100
autoscaling?

Let the cluster autoscaler run between min and max nodes. Price it at max: a new pool often goes there in its first minutes.

reservation?ResourceIdParam

The GPU reservation the pool's nodes draw on; the pool never grows past its unused GPUs.

Match^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length1 <= length <= 63
deferUpgrade?boolean

Keep the pool on its version when the cluster's is raised, as Cluster API's defer-upgrade annotation does. A deferred pool adds no nodes until it follows the cluster, since kubeadm joins a node only at the control plane's minor version.

Defaultfalse
labels?

Node labels that Cluster API carries to every node: keys under node-role.kubernetes.io/, or in the node.cluster.x-k8s.io and node-restriction.kubernetes.io domains. Others are refused, since Cluster API would not carry them.

Propertiesproperties <= 64
taints?array<>

Taints each new node registers with, as kubeadm's nodeRegistration.taints.

Itemsitems <= 16
publicIp?PublicIpMode

shared, the default: nodes have no address of their own. dedicated: each node takes its own public IPv4 address, its ExternalIP.

rollout?

How a change that replaces nodes rolls out, as the MachineDeployment's rolling update. Cluster API's defaults without it.

imageDisk?

The disk each node keeps its container images and layers on. Without it a pool gets 128 GiB when its size has GPUs and 64 GiB otherwise. A change replaces the pool's nodes as rollout says; running nodes never change disks otherwise.

Response Body

Accepted, with the cluster's new generation in the pool's generation. A replay returns the pool's current state.

application/json
  1. response

A pool of nodes.

name*string
cluster*ClusterId

cl- and 16 lowercase hex digits, a DNS label that names the cluster in management.

Match^cl-[0-9a-f]{16}$
location*LocationId

A location id from GET /v1/locations, such as us-west-1.

Match^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length1 <= length <= 63
size*SizeId

A size id from GET /v1/sizes, such as s1.4x. Read ids from that list; do not build them.

Match^[a-z0-9]([-.a-z0-9]*[a-z0-9])?$
Length1 <= length <= 63
replicas?integer

How many nodes the pool asks for. Absent when it autoscales.

autoscaling?

The bounds the cluster autoscaler keeps the pool within.

reservation?ReservationId

Opaque. Starts with r-; otherwise as instance ids.

Match^r-[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Lengthlength <= 63
kubernetesVersion?KubernetesVersion

The version the pool's nodes run, as Cluster API reports it. Absent until the pool first reports one.

Match^v[0-9]+\.[0-9]+\.[0-9]+$
Lengthlength <= 32
deferUpgrade*boolean
labels*

Labels. May include keys with a reserved prefix, such as cloud.confidential.ai/, which the platform sets.

taints*array<>
publicIp*PublicIpMode

Open set; accept values not listed.

rollout?

The pool's rolling update. Absent where it takes Cluster API's defaults.

imageDisk?

The image disk its nodes have. Absent for a pool made before pools had one, whose nodes have none until one is set.

status*NodePoolStatus

Open set; accept values not listed. As for clusters.

upgrade?

The pool's move to its cluster's upgrade target, absent while it is not moving. The pool keeps its size while it moves.

reason?

What holds the pool's nodes from Ready: the most pressing of what holds each node on the pool's current template. Absent when nothing does.

statusChangedAt*string
Formatdate-time
conditions*array<>

The MachineDeployment's conditions.

generation*integer

The cluster's generation, which every change to the pool raises.

Range1 <= value
observedGeneration*integer

The cluster's observed generation, which Cluster API has rendered into the pool.

Range0 <= value
nodes*

The pool's nodes, as its MachineDeployment reports them. All 0 until management first reports.

createdAt*string
Formatdate-time
Example Request
curl -X POST 'https://api.cloud.confidential.ai/v1/clusters/cl-0123456789abcdef/node-pools' \  -H 'Idempotency-Key: 0b9d6c1e-5f8a-4c2e-9a51-2f7e0c3d4b18' \  -H 'Api-Version: 2026-10-15' \  -H 'X-Correlation-ID: rollout-2026-10-22' \  -H 'Access-Reason: Support ticket 4821: customer asked why i-6d3f9h2k8mzr failed' \  -H 'Content-Type: application/json' \  -d '{  "name": "gpu",  "location": "us-west-1",  "size": "g1-b300.2x",  "autoscaling": {    "min": 0,    "max": 2  },  "reservation": "r-5mf2k9x3qp",  "labels": {    "node.cluster.x-k8s.io/accelerator": "b300"  },  "taints": [    {      "key": "nvidia.com/gpu",      "value": "present",      "effect": "NoSchedule"    }  ]}'
Example Response
{  "name": "gpu",  "cluster": "cl-0123456789abcdef",  "location": "us-west-1",  "size": "g1-b300.2x",  "autoscaling": {    "min": 0,    "max": 2  },  "reservation": "r-5mf2k9x3qp",  "deferUpgrade": false,  "labels": {    "node.cluster.x-k8s.io/accelerator": "b300"  },  "taints": [    {      "key": "nvidia.com/gpu",      "value": "present",      "effect": "NoSchedule"    }  ],  "publicIp": "shared",  "status": "provisioning",  "statusChangedAt": "2026-10-24T22:10:00Z",  "conditions": [],  "generation": 3,  "observedGeneration": 0,  "nodes": {    "replicas": 0,    "desired": 0,    "ready": 0,    "available": 0,    "upToDate": 0  },  "createdAt": "2026-10-24T22:10:00Z"}