Docs
Clusters

Delete a node pool

DELETE
/v1/clusters/{id}/node-pools/{name}

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.

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:delete

Path Parameters

id*string

The cluster id.

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

The node pool's name.

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

Header Parameters

Idempotency-Key?string

Optional. With a key, a repeat of this request is a replay, marked with Idempotent-Replayed: true. 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

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 DELETE 'https://api.cloud.confidential.ai/v1/clusters/cl-0123456789abcdef/node-pools/gpu' \  -H 'Idempotency-Key: 6f1c2e4a-8d3b-4f9e-b7a2-1c5d9e0f3a68' \  -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'
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"}

Change a node pool PATCH

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.

List images GET

Lists the image versions your org can create instances from, by family and then newest version first: those that are `active` or `deprecated`. Each version has one artifact per TEE, with its digest, the sizes it runs on and its signed reference manifest, and a launch contract that says what a create must supply: the disks, the access mode, the init-data formats and the minimum memory. An artifact appears once it passes the platform's boot test on its TEE, and it lists a GPU size only once its image passes GPU acceptance with that many GPUs. `image: "<family>"` in a create resolves to the family's newest `active` version; `image: "<family>@<version>"` pins one. Until a new version has passed the boot test on a TEE, creates on that TEE that name the family get the newest active version that has, or if none has, the newest deprecated version still accepting creates that has; when no host with room has booted that one, the version before it. Among those versions, the newest that sells the create's size comes first, so a version that does not sell the size yet leaves its creates on the one before it. A version none of whose artifacts has passed is not listed. A `deprecated` version still runs its instances and accepts creates until `createsEndAt`; after that it is retired and no longer listed. A version withdrawn for a security flaw is retired the same day, and every org with an instance on it is told. Those instances keep running unless the flaw endangers their host or other tenants; then the platform stops them after notice, and they become `failed` with reason `image_unavailable`. A version that is not yet active does not exist for your org: a create that names it returns `400 invalid_request` with violation `not_found` at `/image`. A create that names a retired version returns the same error with violation `retired`, and its message names the family's newest version.