Change a node pool
Sets the pool's desired state, as a JSON merge patch of the fields
it names, and returns 202 with the pool. Changing replicas or
autoscaling changes only how many nodes run, and labels update
the nodes in place. Changing location, size, reservation,
taints or kubernetesVersion replaces the pool's nodes, by its
rollout. name never changes.
AuthorizationBearer <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
id*stringThe cluster id.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 63name*stringThe node pool's name.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 63Api-Version*stringThe 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?stringAn 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.
^[A-Za-z0-9._:-]+$1 <= length <= 128Org-Context?stringAdmin 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.
^org-[a-z0-9]([-a-z0-9]*[a-z0-9])?$5 <= length <= 63Access-Reason?stringAdmin 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.
^[^\x00-\x1F\x7F]+$10 <= length <= 500application/json- body
The fields to change, as a JSON merge patch. Set at most one of replicas and autoscaling; setting one switches the pool to it.
1 <= propertieslocation?LocationIdA location id from GET /v1/locations, such as us-west-1.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 63size?SizeIdA size id from GET /v1/sizes, such as s1.4x. Read ids from that
list; do not build them.
^[a-z0-9]([-.a-z0-9]*[a-z0-9])?$1 <= length <= 63replicas?integer0 <= value <= 100autoscaling?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?ResourceIdParamA resource id, exactly as the API returned it.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 63deferUpgrade?booleanlabels?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.
properties <= 64taints?array<>items <= 16publicIp?PublicIpModeOpen set; accept values not listed.
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.
Accepted, with the cluster's new generation in the pool's
generation. A replay returns the pool's current state.
application/json- response
A pool of nodes.
name*stringcluster*ClusterIdcl- and 16 lowercase hex digits, a DNS label that names the cluster in management.
^cl-[0-9a-f]{16}$location*LocationIdA location id from GET /v1/locations, such as us-west-1.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 63size*SizeIdA size id from GET /v1/sizes, such as s1.4x. Read ids from that
list; do not build them.
^[a-z0-9]([-.a-z0-9]*[a-z0-9])?$1 <= length <= 63replicas?integerHow many nodes the pool asks for. Absent when it autoscales.
autoscaling?The bounds the cluster autoscaler keeps the pool within.
reservation?ReservationIdOpaque. Starts with r-; otherwise as instance ids.
^r-[a-z0-9]([-a-z0-9]*[a-z0-9])?$length <= 63kubernetesVersion?KubernetesVersionThe version the pool's nodes run, as Cluster API reports it. Absent until the pool first reports one.
^v[0-9]+\.[0-9]+\.[0-9]+$length <= 32deferUpgrade*booleanlabels*Labels. May include keys with a reserved prefix, such as cloud.confidential.ai/, which the platform sets.
taints*array<>publicIp*PublicIpModeOpen 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*NodePoolStatusOpen 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*stringdate-timeconditions*array<>The MachineDeployment's conditions.
generation*integerThe cluster's generation, which every change to the pool raises.
1 <= valueobservedGeneration*integerThe cluster's observed generation, which Cluster API has rendered into the pool.
0 <= valuenodes*The pool's nodes, as its MachineDeployment reports them. All 0 until management first reports.
createdAt*stringdate-timecurl -X PATCH 'https://api.cloud.confidential.ai/v1/clusters/cl-0123456789abcdef/node-pools/gpu' \ -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 '{ "replicas": 5}'{ "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"}Get a node pool GET
Returns the pool, with its replicas as Cluster API reports them.
Delete a node pool DELETE
Deletes the pool and its nodes, drained by Cluster API. This cannot be undone. Returns `202` with the pool `terminating`, and the pool is `404` from then on. A retry with the Idempotency-Key returns the first answer.