Docs
Clusters

Get what you sign for a cluster's CDS

GET
/v1/clusters/{id}/cds

Returns what the c8s commands need to build, start and verify the cluster's CDS: in launchInputs, what c8s cds config new takes; then the launch file every replica boots, the pin that binds it, each replica's address, each pool's worker document, image and image manifest, and whether the decree in force admits the pool. The service signs nothing, and nothing here is evidence: decree is the state management last read from the replicas, and no command takes it as input. A part not uploaded yet is left out and listed in pending; nodes of a pool are created only once a decree admits its document.

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

Path Parameters

id*string

The cluster id.

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

Header Parameters

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

What the cluster's CDS decrees are signed over.

application/json
  1. response

What the customer's c8s cds ha commands check and sign for the cluster's CDS. Every document is the exact bytes that are measured, in base64.

cluster*string

The cluster's id.

status*ClusterCdsStatus

Open set; accept values not listed. awaitingLaunchFile until the launch file is uploaded, and no replica is launched before it is; provisioning while the replicas launch; awaitingGenesis once they run, until a Genesis decree starts the CDS; running once it is started; replacing while a failed replica is being replaced; quorumBehind while a majority of the replicas is behind the Genesis and catching up from the leader; quorumLost once the replicas hold the cluster no more, which costs it its CDS and every secret in it; terminating once the cluster is deleted.

pending*array<string>

The parts not uploaded yet, which the response leaves out: launchFile and pin. Open set; accept values not listed.

launchInputs*

What c8s cds config new takes to write the cluster's launch file and its pin. The allowlist seed, the component digests and the CDS image manifest are the c8s release's: take them from the release itself, and compare, rather than trust this response for them; cdsImageReferenceManifest says which blob cdsImageManifest is, so the bytes can be checked against the registry. The ranges and names are the cluster's own, and its CDS keeps them for life: a node subnet reaching into the pod range lets the CDS treat a pod as a node, so check each of nodeCidrs against the published guest subnets of the location and of its satellites, and podCidr and serviceCidr against the published cluster network.

decree?

The node image set in force in the cluster's CDS, as management last read it from the replicas. It is what the service has seen, not evidence, and no command takes it: read c8s cds ha decrees from your own machine for the base version and the set a further decree carries. Absent until a decree is in force.

launchFile?string

The c8s-cds/v1 launch file every replica boots, as the customer uploaded it.

Formatbyte
pin?string

The pin document that names the cluster's CDS images and binds the launch file, which every worker document carries.

Formatbyte
replicas*array<>

The CDS replicas, by index. Empty until the launch file is uploaded.

nodePools*array<>

The cluster's pools, by name.

Example Request
curl -X GET 'https://api.cloud.confidential.ai/v1/clusters/cl-0123456789abcdef/cds' \  -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
{  "cluster": "cl-0123456789abcdef",  "status": "running",  "pending": [],  "launchInputs": {    "c8sRelease": "v0.99.26-2-g173b9d467",    "replicaNames": [      "r0.cds.cl-0123456789abcdef.us-west-1.k8s.confidential.ai",      "r1.cds.cl-0123456789abcdef.us-west-1.k8s.confidential.ai",      "r2.cds.cl-0123456789abcdef.us-west-1.k8s.confidential.ai"    ],    "voters": 3,    "nodeCidr": "10.48.64.0/18",    "nodeCidrs": [      "10.48.64.0/18"    ],    "podCidr": "10.243.0.0/16",    "serviceCidr": "10.95.0.0/16",    "leafDnsName": "ingress.cl-0123456789abcdef.us-west-1.k8s.confidential.ai",    "leafDnsPattern": "^[a-z0-9-]+[.][a-z0-9-]+[.]svc$",    "allowlistSeed": "eyJzY2hlbWEiOiJjOHMuYWxsb3dsaXN0L3YxIiwid29ya2xvYWRzIjp7fX0=",    "components": {      "operator": "sha256:8c780b3655fc55a663ed38174927e149157c6d2bedf81b9ce60a0a6d8ec33947",      "armtlsMesh": "sha256:3f1a9c0e5b8d47126a4e9f8c3b2d5a7e1c6f0b94d28e37a5c1b4f6d9e0a2c8b3"    },    "cdsImageManifest": "eyJ2ZXJzaW9uIjozLCJ0ZHgiOnsibXJ0ZCI6IjkzMDllYWFlIn19",    "cdsImageReferenceManifest": {      "uri": "https://measurements.example/c8s-cds-ha/2026.11.10/tdx/manifest.json",      "digest": "sha256:5d41402abc4b2a76b9719d911017c592a1b2c3d4e5f60718293a4b5c6d7e8f90",      "logEntry": "rekor:1293847"    }  },  "decree": {    "version": 1,    "intentId": "01JCZ8Q0W9N4V7F6K2R5M3T8XB"  },  "launchFile": "c2NoZW1hVmVyc2lvbjogYzhzLWNkcy92MQo=",  "pin": "eyJtZWFzdXJlbWVudHMiOltdfQ==",  "replicas": [    {      "index": 0,      "address": "r0.cds.cl-0123456789abcdef.us-west-1.k8s.confidential.ai:8443",      "status": "running"    },    {      "index": 1,      "address": "r1.cds.cl-0123456789abcdef.us-west-1.k8s.confidential.ai:8443",      "status": "running"    },    {      "index": 2,      "address": "r2.cds.cl-0123456789abcdef.us-west-1.k8s.confidential.ai:8443",      "status": "running"    }  ],  "nodePools": [    {      "name": "web",      "admitted": true,      "document": "c2NoZW1hVmVyc2lvbjogYzhzLXdvcmtlci92MQo=",      "documentDigest": "4f2c1d8e9a0b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5",      "workerImage": "c8s-worker@2026.11.10",      "workerImageManifest": "eyJ2ZXJzaW9uIjozLCJ0ZHgiOnsibXJ0ZCI6IjkzMDllYWFlIn19",      "workerImageReferenceManifest": {        "uri": "https://measurements.example/c8s-worker/2026.11.10/tdx/manifest.json",        "digest": "sha256:0b1d4c5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f80912",        "logEntry": "rekor:1293952"      }    }  ]}

Delete a cluster DELETE

Deletes the cluster, its pools and their nodes. This cannot be undone. Returns `202` with the cluster `terminating`; it is gone, and `404`, once Cluster API has removed every node and the control plane, and its name is free. Volumes whose `retention` is `retain` stay. A repeat returns the cluster as it is, and a retry with the Idempotency-Key once it is gone returns the first answer.

Upload the launch file and pin of a cluster's CDS PUT

Takes the two files `c8s cds config new` wrote for the cluster, the launch file every CDS replica boots and the pin that binds it to the release's CDS image, and starts the replicas from them. The bytes are stored as they are: clients pin the launch file and every worker document carries the pin, so nothing is rendered or substituted here. Each file is checked against what this cluster's CDS must be, and a file that fails returns `400 invalid_request` naming the field: the cluster's id, its replica names, its router's DNS name, its location's guest subnet, a voter seat for each API server replica, the c8s release's allowlist seed, and, for the pin, the measurements of that release's CDS image bound to this launch file. A launch file that names nodes, a Pod image policy or a KMS is refused. `GET /v1/clusters/{id}/cds` serves every input the command takes. The two files are taken once: a second upload is `409 invalid_state`, and a `terminating` cluster the same. Returns `202` with the cluster; `GET /v1/clusters/{id}/cds` then shows the replicas starting.