Clusters

Clusters, their nodes and agents, and the commands that install, join and upgrade them. Each operation lists its method and path, parameters, request body, responses and an example call.

List cluster events across every cluster in the active organization.

GET/api/v1/cluster-events

Authorization

AuthorizationBearer <token>

An API token, sent as Authorization: Bearer <token>. A token belongs to one organization and has the role it was created with, so it needs no X-Nebula-Organization header; if you send one, it must name the token's organization.

In: header

Query Parameters

cursor?string

Opaque cursor from a previous response's nextCursor. Omit for the first page.

limit?integer

How many items to return.

Formatint64

Range1 <= value <= 200

Default50

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/api/v1/cluster-events"

{  "$schema": "https://example.com/PageOrganizationEventBody.json",  "items": [    {      "at": "2019-08-24T14:15:22Z",      "clusterId": "string",      "environmentId": "string",      "id": "string",      "kind": "string",      "payload": null,      "releaseId": "string",      "serviceId": "string"    }  ],  "nextCursor": "string"}

List clusters in the active organization, optionally with a fleet summary.

GET/api/v1/clusters

Authorization

AuthorizationBearer <token>

In: header

Query Parameters

cursor?string

Opaque cursor from a previous response's nextCursor. Omit for the first page.

limit?integer

How many items to return.

Formatint64

Range1 <= value <= 200

Default50

include?"summary"

Set to "summary" to include per-cluster fleet summary fields.

Value in

"summary"

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/api/v1/clusters"

{  "$schema": "https://example.com/PageClusterBody.json",  "items": [    {      "$schema": "https://example.com/ClusterBody.json",      "agentVersion": "string",      "apiServerUrl": "string",      "appliedRevision": 0,      "capabilities": {        "buildOptions": true,        "buildRegistry": true,        "builderAuto": true,        "certificateSecrets": true,        "cloudNativePG": true,        "cloudNativePGBackupPlugin": true,        "databaseRestore": true,        "defaultStorageClass": "string",        "edgeFronting": true,        "edgeIngressIPs": [          "string"        ],        "expandableStorageClasses": [          "string"        ],        "fileMounts": true,        "heldSpecs": true,        "heldSuspend": true,        "ingressIPs": [          "string"        ],        "kindMetrics": true,        "metricsServer": true,        "nodeTailscale": true,        "processArgs": true,        "railpackBuilds": true,        "releaseCommand": true,        "storageClasses": [          "string"        ],        "tailscale": true,        "tailscaleEgressProxyGroup": "string",        "traefik": true,        "traefikCertResolvers": [          "string"        ],        "trafficMetrics": true      },      "compileError": "string",      "createdAt": "2019-08-24T14:15:22Z",      "desiredRevision": 0,      "haState": "single",      "highlyAvailable": true,      "id": "string",      "k3sUpdate": {        "current": "string",        "minor": {          "version": "string"        },        "patch": {          "version": "string"        }      },      "k3sVersion": "string",      "lastHeartbeatAt": "2019-08-24T14:15:22Z",      "meshIndex": 0,      "name": "string",      "nodeCount": 0,      "podCidr": "string",      "reconcileError": "string",      "region": "string",      "schedulable": true,      "serverCount": 0,      "serviceCidr": "string",      "slug": "string",      "status": "awaiting-agent",      "summary": {        "agentUpdateAvailable": true,        "nodesReady": 0,        "nodesTotal": 0,        "workloads": 0      }    }  ],  "nextCursor": "string"}

Create a cluster and issue its install command.

POST/api/v1/clusters

Authorization

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Length1 <= length

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/v1/clusters" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'

{  "$schema": "https://example.com/CreateClusterBody.json",  "cluster": {    "$schema": "https://example.com/ClusterBody.json",    "agentVersion": "string",    "apiServerUrl": "string",    "appliedRevision": 0,    "capabilities": {      "buildOptions": true,      "buildRegistry": true,      "builderAuto": true,      "certificateSecrets": true,      "cloudNativePG": true,      "cloudNativePGBackupPlugin": true,      "databaseRestore": true,      "defaultStorageClass": "string",      "edgeFronting": true,      "edgeIngressIPs": [        "string"      ],      "expandableStorageClasses": [        "string"      ],      "fileMounts": true,      "heldSpecs": true,      "heldSuspend": true,      "ingressIPs": [        "string"      ],      "kindMetrics": true,      "metricsServer": true,      "nodeTailscale": true,      "processArgs": true,      "railpackBuilds": true,      "releaseCommand": true,      "storageClasses": [        "string"      ],      "tailscale": true,      "tailscaleEgressProxyGroup": "string",      "traefik": true,      "traefikCertResolvers": [        "string"      ],      "trafficMetrics": true    },    "compileError": "string",    "createdAt": "2019-08-24T14:15:22Z",    "desiredRevision": 0,    "haState": "single",    "highlyAvailable": true,    "id": "string",    "k3sUpdate": {      "current": "string",      "minor": {        "version": "string"      },      "patch": {        "version": "string"      }    },    "k3sVersion": "string",    "lastHeartbeatAt": "2019-08-24T14:15:22Z",    "meshIndex": 0,    "name": "string",    "nodeCount": 0,    "podCidr": "string",    "reconcileError": "string",    "region": "string",    "schedulable": true,    "serverCount": 0,    "serviceCidr": "string",    "slug": "string",    "status": "awaiting-agent",    "summary": {      "agentUpdateAvailable": true,      "nodesReady": 0,      "nodesTotal": 0,      "workloads": 0    }  },  "expiresAt": "2019-08-24T14:15:22Z",  "installCommand": "string",  "token": "string"}

GET/api/v1/clusters/ssh-key

Authorization

AuthorizationBearer <token>

In: header

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/api/v1/clusters/ssh-key"

{  "$schema": "https://example.com/SshKeyBody.json",  "publicKey": "string"}

Get one cluster.

GET/api/v1/clusters/{id}

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/api/v1/clusters/string"

{  "$schema": "https://example.com/ClusterBody.json",  "agentVersion": "string",  "apiServerUrl": "string",  "appliedRevision": 0,  "capabilities": {    "buildOptions": true,    "buildRegistry": true,    "builderAuto": true,    "certificateSecrets": true,    "cloudNativePG": true,    "cloudNativePGBackupPlugin": true,    "databaseRestore": true,    "defaultStorageClass": "string",    "edgeFronting": true,    "edgeIngressIPs": [      "string"    ],    "expandableStorageClasses": [      "string"    ],    "fileMounts": true,    "heldSpecs": true,    "heldSuspend": true,    "ingressIPs": [      "string"    ],    "kindMetrics": true,    "metricsServer": true,    "nodeTailscale": true,    "processArgs": true,    "railpackBuilds": true,    "releaseCommand": true,    "storageClasses": [      "string"    ],    "tailscale": true,    "tailscaleEgressProxyGroup": "string",    "traefik": true,    "traefikCertResolvers": [      "string"    ],    "trafficMetrics": true  },  "compileError": "string",  "createdAt": "2019-08-24T14:15:22Z",  "desiredRevision": 0,  "haState": "single",  "highlyAvailable": true,  "id": "string",  "k3sUpdate": {    "current": "string",    "minor": {      "version": "string"    },    "patch": {      "version": "string"    }  },  "k3sVersion": "string",  "lastHeartbeatAt": "2019-08-24T14:15:22Z",  "meshIndex": 0,  "name": "string",  "nodeCount": 0,  "podCidr": "string",  "reconcileError": "string",  "region": "string",  "schedulable": true,  "serverCount": 0,  "serviceCidr": "string",  "slug": "string",  "status": "awaiting-agent",  "summary": {    "agentUpdateAvailable": true,    "nodesReady": 0,    "nodesTotal": 0,    "workloads": 0  }}

Rename a cluster, or cordon/uncordon every node in it.

PATCH/api/v1/clusters/{id}

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

Length1 <= length

schedulable?boolean

Response Body

`application/json`

`application/problem+json`

curl -X PATCH "https://example.com/api/v1/clusters/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "$schema": "https://example.com/ClusterBody.json",  "agentVersion": "string",  "apiServerUrl": "string",  "appliedRevision": 0,  "capabilities": {    "buildOptions": true,    "buildRegistry": true,    "builderAuto": true,    "certificateSecrets": true,    "cloudNativePG": true,    "cloudNativePGBackupPlugin": true,    "databaseRestore": true,    "defaultStorageClass": "string",    "edgeFronting": true,    "edgeIngressIPs": [      "string"    ],    "expandableStorageClasses": [      "string"    ],    "fileMounts": true,    "heldSpecs": true,    "heldSuspend": true,    "ingressIPs": [      "string"    ],    "kindMetrics": true,    "metricsServer": true,    "nodeTailscale": true,    "processArgs": true,    "railpackBuilds": true,    "releaseCommand": true,    "storageClasses": [      "string"    ],    "tailscale": true,    "tailscaleEgressProxyGroup": "string",    "traefik": true,    "traefikCertResolvers": [      "string"    ],    "trafficMetrics": true  },  "compileError": "string",  "createdAt": "2019-08-24T14:15:22Z",  "desiredRevision": 0,  "haState": "single",  "highlyAvailable": true,  "id": "string",  "k3sUpdate": {    "current": "string",    "minor": {      "version": "string"    },    "patch": {      "version": "string"    }  },  "k3sVersion": "string",  "lastHeartbeatAt": "2019-08-24T14:15:22Z",  "meshIndex": 0,  "name": "string",  "nodeCount": 0,  "podCidr": "string",  "reconcileError": "string",  "region": "string",  "schedulable": true,  "serverCount": 0,  "serviceCidr": "string",  "slug": "string",  "status": "awaiting-agent",  "summary": {    "agentUpdateAvailable": true,    "nodesReady": 0,    "nodesTotal": 0,    "workloads": 0  }}

Remove a cluster after every environment is unbound.

DELETE/api/v1/clusters/{id}

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

`application/problem+json`

curl -X DELETE "https://example.com/api/v1/clusters/string"

Empty

Get a cluster's agent update status and history.

GET/api/v1/clusters/{id}/agent

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/api/v1/clusters/string/agent"

{  "$schema": "https://example.com/AgentStatusBody.json",  "availableImage": "string",  "currentImage": "string",  "currentVersion": "string",  "history": [    {      "$schema": "https://example.com/AgentUpdateAttemptBody.json",      "finishedAt": "2019-08-24T14:15:22Z",      "fromImage": "string",      "id": "string",      "kind": "string",      "message": "string",      "startedAt": "2019-08-24T14:15:22Z",      "status": "string",      "toImage": "string"    }  ],  "inProgress": {    "id": "string",    "startedAt": "2019-08-24T14:15:22Z",    "toImage": "string"  },  "updateAvailable": true}

Roll a cluster's agent back to an image it has already run.

POST/api/v1/clusters/{id}/agent/rollback

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

image*string

Length1 <= length

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/v1/clusters/string/agent/rollback" \  -H "Content-Type: application/json" \  -d '{    "image": "string"  }'

{  "$schema": "https://example.com/AgentUpdateAttemptBody.json",  "finishedAt": "2019-08-24T14:15:22Z",  "fromImage": "string",  "id": "string",  "kind": "string",  "message": "string",  "startedAt": "2019-08-24T14:15:22Z",  "status": "string",  "toImage": "string"}

Update a cluster's agent to a new image, defaulting to the control plane's own.

POST/api/v1/clusters/{id}/agent/update

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

image?string

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/v1/clusters/string/agent/update" \  -H "Content-Type: application/json" \  -d '{}'

{  "$schema": "https://example.com/AgentUpdateAttemptBody.json",  "finishedAt": "2019-08-24T14:15:22Z",  "fromImage": "string",  "id": "string",  "kind": "string",  "message": "string",  "startedAt": "2019-08-24T14:15:22Z",  "status": "string",  "toImage": "string"}

Issue the command that installs CloudNativePG, cert-manager and the Barman Cloud Plugin on this cluster.

POST/api/v1/clusters/{id}/cnpg

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/v1/clusters/string/cnpg"

{  "$schema": "https://example.com/HostScriptCommandBody.json",  "command": "string",  "expiresAt": "2019-08-24T14:15:22Z",  "token": "string"}

Replace a cluster's single-use enrollment token.

POST/api/v1/clusters/{id}/enrollment-token

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/v1/clusters/string/enrollment-token"

{  "$schema": "https://example.com/EnrollmentTokenBody.json",  "expiresAt": "2019-08-24T14:15:22Z",  "installCommand": "string",  "token": "string"}

List a cluster's most recent events.

GET/api/v1/clusters/{id}/events

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Query Parameters

cursor?string

Opaque cursor from a previous response's nextCursor. Omit for the first page.

limit?integer

How many items to return.

Formatint64

Range1 <= value <= 200

Default50

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/api/v1/clusters/string/events"

{  "$schema": "https://example.com/PageEventBody.json",  "items": [    {      "at": "2019-08-24T14:15:22Z",      "environmentId": "string",      "id": "string",      "kind": "string",      "payload": null,      "releaseId": "string",      "serviceId": "string"    }  ],  "nextCursor": "string"}

Atomically promote a one-server cluster to three servers.

POST/api/v1/clusters/{id}/high-availability

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/v1/clusters/string/high-availability"

{  "$schema": "https://example.com/HighAvailabilityBody.json",  "retrofit": {    "$schema": "https://example.com/HostScriptCommandBody.json",    "command": "string",    "expiresAt": "2019-08-24T14:15:22Z",    "token": "string"  },  "serverJoins": [    {      "expiresAt": "2019-08-24T14:15:22Z",      "installCommand": "string",      "token": "string"    },    {      "expiresAt": "2019-08-24T14:15:22Z",      "installCommand": "string",      "token": "string"    }  ]}

Get the live install progress every node has reported for this cluster.

GET/api/v1/clusters/{id}/install

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/api/v1/clusters/string/install"

{  "$schema": "https://example.com/InstallStepsBody.json",  "steps": [    {      "logTail": "string",      "message": "string",      "nodeName": "string",      "status": "string",      "step": "string",      "updatedAt": "2019-08-24T14:15:22Z"    }  ]}

Issue a short-lived install command that adds a worker to a cluster.

POST/api/v1/clusters/{id}/join-command

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

gateway?boolean

Join as the cluster's public gateway: it alone serves ports 80/443 for the cluster, runs no workloads, and needs a public IPv4 address.

labels?

Kubernetes labels the joining node registers with.

ttlSeconds?integer

How long the command stays usable; defaults to the organization's join token lifetime.

Formatint64

Range300 <= value <= 86400

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/v1/clusters/string/join-command" \  -H "Content-Type: application/json" \  -d '{}'

{  "$schema": "https://example.com/JoinCommandBody.json",  "expiresAt": "2019-08-24T14:15:22Z",  "installCommand": "string",  "joinTokenId": "string",  "token": "string"}

Report a cluster's K3s node versions, available upgrades and the manual upgrade steps.

GET/api/v1/clusters/{id}/k3s-upgrade

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/api/v1/clusters/string/k3s-upgrade"

{  "$schema": "https://example.com/K3sUpgradeBody.json",  "checkError": "string",  "checkedAt": "2019-08-24T14:15:22Z",  "checks": [    {      "detail": "string",      "name": "string",      "state": "ok"    }  ],  "current": "string",  "minor": {    "version": "string"  },  "minorSteps": [    {      "command": "string",      "detail": "string",      "title": "string"    }  ],  "minorsBehindStable": 0,  "nodes": [    {      "name": "string",      "ready": true,      "role": "server",      "version": "string"    }  ],  "patch": {    "version": "string"  },  "patchSteps": [    {      "command": "string",      "detail": "string",      "title": "string"    }  ]}

Report a cluster's allocated vs allocatable CPU and memory over a trailing window.

GET/api/v1/clusters/{id}/metrics

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Query Parameters

window?string

Trailing window to report.

Value in

"1h"
"6h"
"24h"

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/api/v1/clusters/string/metrics"

{  "$schema": "https://example.com/ClusterMetricsBody.json",  "samples": [    {      "allocatableCpuMilli": 0,      "allocatableMemoryBytes": 0,      "allocatedCpuMilli": 0,      "allocatedMemoryBytes": 0,      "at": "2019-08-24T14:15:22Z"    }  ]}

List a cluster's nodes.

GET/api/v1/clusters/{id}/nodes

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Query Parameters

cursor?string

Opaque cursor from a previous response's nextCursor. Omit for the first page.

limit?integer

How many items to return.

Formatint64

Range1 <= value <= 200

Default50

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/api/v1/clusters/string/nodes"

{  "$schema": "https://example.com/PageNodeBody.json",  "items": [    {      "address": "string",      "allocatable": {        "cpuMilli": 0,        "ephemeralBytes": 0,        "memoryBytes": 0,        "pods": 0      },      "allocated": {        "cpuMilli": 0,        "ephemeralBytes": 0,        "memoryBytes": 0,        "pods": 0      },      "conditions": [        {          "lastTransition": "2019-08-24T14:15:22Z",          "message": "string",          "reason": "string",          "status": "string",          "type": "string"        }      ],      "containerRuntime": "string",      "createdAt": "2019-08-24T14:15:22Z",      "labels": {        "property1": "string",        "property2": "string"      },      "name": "string",      "ready": true,      "region": "string",      "roles": [        "string"      ],      "taints": [        {          "effect": "string",          "key": "string",          "value": "string"        }      ],      "unschedulable": true,      "updatedAt": "2019-08-24T14:15:22Z"    }  ],  "nextCursor": "string"}

Cordon a node so it receives no new pods.

POST/api/v1/clusters/{id}/nodes/{name}/cordon

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

name*string

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/v1/clusters/string/nodes/string/cordon"

{  "$schema": "https://example.com/Command.json",  "buildId": "string",  "database": {    "maxRows": 0,    "query": "string",    "target": {      "database": "string",      "engine": "string",      "image": "string",      "namespace": "string",      "password": "string",      "port": 0,      "runAsUser": 0,      "serviceSlug": "string",      "username": "string"    },    "timeoutMillis": 0  },  "environmentId": "string",  "id": "string",  "image": "string",  "kind": "string",  "node": "string",  "pod": "string",  "process": "string",  "releaseId": "string",  "role": "string",  "serviceId": "string",  "volume": {    "database": {      "database": "string",      "engine": "string",      "image": "string",      "namespace": "string",      "password": "string",      "port": 0,      "runAsUser": 0,      "serviceSlug": "string",      "username": "string"    },    "environmentId": "string",    "expectedSha256": "string",    "jobId": "string",    "method": "string",    "namespace": "string",    "objectKey": "string",    "quiesce": true,    "serviceId": "string",    "serviceSlug": "string",    "store": {      "accessKeyId": "string",      "bucket": "string",      "endpoint": "string",      "forcePathStyle": true,      "region": "string",      "secretAccessKey": "string"    },    "volume": {      "mountPath": "string",      "name": "string",      "sizeBytes": 0,      "storageClass": "string"    }  }}

Drain non-DaemonSet pods from a node.

POST/api/v1/clusters/{id}/nodes/{name}/drain

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

name*string

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/v1/clusters/string/nodes/string/drain"

{  "$schema": "https://example.com/Command.json",  "buildId": "string",  "database": {    "maxRows": 0,    "query": "string",    "target": {      "database": "string",      "engine": "string",      "image": "string",      "namespace": "string",      "password": "string",      "port": 0,      "runAsUser": 0,      "serviceSlug": "string",      "username": "string"    },    "timeoutMillis": 0  },  "environmentId": "string",  "id": "string",  "image": "string",  "kind": "string",  "node": "string",  "pod": "string",  "process": "string",  "releaseId": "string",  "role": "string",  "serviceId": "string",  "volume": {    "database": {      "database": "string",      "engine": "string",      "image": "string",      "namespace": "string",      "password": "string",      "port": 0,      "runAsUser": 0,      "serviceSlug": "string",      "username": "string"    },    "environmentId": "string",    "expectedSha256": "string",    "jobId": "string",    "method": "string",    "namespace": "string",    "objectKey": "string",    "quiesce": true,    "serviceId": "string",    "serviceSlug": "string",    "store": {      "accessKeyId": "string",      "bucket": "string",      "endpoint": "string",      "forcePathStyle": true,      "region": "string",      "secretAccessKey": "string"    },    "volume": {      "mountPath": "string",      "name": "string",      "sizeBytes": 0,      "storageClass": "string"    }  }}

Uncordon a node so it can receive pods again.

POST/api/v1/clusters/{id}/nodes/{name}/uncordon

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

name*string

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/v1/clusters/string/nodes/string/uncordon"

{  "$schema": "https://example.com/Command.json",  "buildId": "string",  "database": {    "maxRows": 0,    "query": "string",    "target": {      "database": "string",      "engine": "string",      "image": "string",      "namespace": "string",      "password": "string",      "port": 0,      "runAsUser": 0,      "serviceSlug": "string",      "username": "string"    },    "timeoutMillis": 0  },  "environmentId": "string",  "id": "string",  "image": "string",  "kind": "string",  "node": "string",  "pod": "string",  "process": "string",  "releaseId": "string",  "role": "string",  "serviceId": "string",  "volume": {    "database": {      "database": "string",      "engine": "string",      "image": "string",      "namespace": "string",      "password": "string",      "port": 0,      "runAsUser": 0,      "serviceSlug": "string",      "username": "string"    },    "environmentId": "string",    "expectedSha256": "string",    "jobId": "string",    "method": "string",    "namespace": "string",    "objectKey": "string",    "quiesce": true,    "serviceId": "string",    "serviceSlug": "string",    "store": {      "accessKeyId": "string",      "bucket": "string",      "endpoint": "string",      "forcePathStyle": true,      "region": "string",      "secretAccessKey": "string"    },    "volume": {      "mountPath": "string",      "name": "string",      "sizeBytes": 0,      "storageClass": "string"    }  }}

Start adding a machine over SSH: fetch its host key for the operator to confirm.

POST/api/v1/clusters/{id}/ssh-installs

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

gateway?boolean

Install as the cluster's public gateway: it alone serves ports 80/443 for the cluster, runs no workloads, and needs a public IPv4 address.

host*string

Hostname or IP address of the machine. Public addresses are required unless privateAddress is explicitly enabled.

Length1 <= length

labels?

Kubernetes labels the machine registers with.

port?integer

SSH port; 22 when omitted.

Formatint64

Range1 <= value <= 65535

privateAddress?boolean

Allow an RFC 1918, unique-local or shared CGNAT IP literal. Requires a signed-in organization owner; loopback and link-local addresses remain forbidden.

username*string

Account to sign in as; needs passwordless sudo unless it is root.

Length1 <= length

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/v1/clusters/string/ssh-installs" \  -H "Content-Type: application/json" \  -d '{    "host": "string",    "username": "string"  }'

{  "$schema": "https://example.com/SshInstallBody.json",  "clusterId": "string",  "createdAt": "2019-08-24T14:15:22Z",  "fingerprint": "string",  "host": "string",  "hostKeyType": "string",  "id": "string",  "joinTokenId": "string",  "labels": {    "property1": "string",    "property2": "string"  },  "message": "string",  "port": 0,  "status": "fingerprint",  "updatedAt": "2019-08-24T14:15:22Z",  "username": "string"}

Use the request body type in TypeScript.

clientId*string

Length1 <= length

clientSecret*string

Length1 <= length

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/v1/clusters/string/tailscale" \  -H "Content-Type: application/json" \  -d '{    "clientId": "string",    "clientSecret": "string"  }'

{  "$schema": "https://example.com/TailscaleConnectBody.json",  "command": "string",  "expiresAt": "2019-08-24T14:15:22Z",  "token": "string"}

limit?integer

How many items to return.

Formatint64

Range1 <= value <= 200

Default50

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/api/v1/clusters/string/workloads"

{  "$schema": "https://example.com/PageWorkloadBody.json",  "items": [    {      "environmentId": "string",      "environmentSlug": "string",      "namespace": "string",      "production": true,      "serviceId": "string",      "serviceName": "string",      "serviceSlug": "string"    }  ],  "nextCursor": "string"}

limit?integer

How many items to return.

Formatint64

Range1 <= value <= 200

Default50

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/api/v1/join-tokens"

{  "$schema": "https://example.com/PageJoinTokenBody.json",  "items": [    {      "$schema": "https://example.com/JoinTokenBody.json",      "clusterId": "string",      "createdAt": "2019-08-24T14:15:22Z",      "createdBy": "string",      "expiresAt": "2019-08-24T14:15:22Z",      "gateway": true,      "id": "string",      "labels": {        "property1": "string",        "property2": "string"      },      "prefix": "string",      "purpose": "join",      "revokedAt": "2019-08-24T14:15:22Z",      "role": "worker",      "status": "active",      "usedAt": "2019-08-24T14:15:22Z",      "usedByNode": "string"    }  ],  "nextCursor": "string"}

`application/json`

`application/problem+json`

curl -X DELETE "https://example.com/api/v1/join-tokens/string"

{  "$schema": "https://example.com/JoinTokenBody.json",  "clusterId": "string",  "createdAt": "2019-08-24T14:15:22Z",  "createdBy": "string",  "expiresAt": "2019-08-24T14:15:22Z",  "gateway": true,  "id": "string",  "labels": {    "property1": "string",    "property2": "string"  },  "prefix": "string",  "purpose": "join",  "revokedAt": "2019-08-24T14:15:22Z",  "role": "worker",  "status": "active",  "usedAt": "2019-08-24T14:15:22Z",  "usedByNode": "string"}

`application/json`

`application/problem+json`

curl -X GET "https://example.com/api/v1/ssh-installs/string"

{  "$schema": "https://example.com/SshInstallBody.json",  "clusterId": "string",  "createdAt": "2019-08-24T14:15:22Z",  "fingerprint": "string",  "host": "string",  "hostKeyType": "string",  "id": "string",  "joinTokenId": "string",  "labels": {    "property1": "string",    "property2": "string"  },  "message": "string",  "port": 0,  "status": "fingerprint",  "updatedAt": "2019-08-24T14:15:22Z",  "username": "string"}

`application/json`

`application/problem+json`

curl -X POST "https://example.com/api/v1/ssh-installs/string/confirm"

{  "$schema": "https://example.com/SshInstallBody.json",  "clusterId": "string",  "createdAt": "2019-08-24T14:15:22Z",  "fingerprint": "string",  "host": "string",  "hostKeyType": "string",  "id": "string",  "joinTokenId": "string",  "labels": {    "property1": "string",    "property2": "string"  },  "message": "string",  "port": 0,  "status": "fingerprint",  "updatedAt": "2019-08-24T14:15:22Z",  "username": "string"}

Clusters

List cluster events across every cluster in the active organization.Copy Anchor Link

AuthorizationCopy Anchor Link

Query ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

List clusters in the active organization, optionally with a fleet summary.Copy Anchor Link

AuthorizationCopy Anchor Link

Query ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

Create a cluster and issue its install command.Copy Anchor Link

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

201application/json

defaultapplication/problem+json

Get the public key SSH installs sign in with, creating it on first use.Copy Anchor Link

AuthorizationCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

Get one cluster.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

Rename a cluster, or cordon/uncordon every node in it.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

Remove a cluster after every environment is unbound.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

204

defaultapplication/problem+json

Get a cluster's agent update status and history.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

Roll a cluster's agent back to an image it has already run.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

Update a cluster's agent to a new image, defaulting to the control plane's own.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

Issue the command that installs CloudNativePG, cert-manager and the Barman Cloud Plugin on this cluster.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

Replace a cluster's single-use enrollment token.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

List a cluster's most recent events.Copy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Query ParametersCopy Anchor Link

Response BodyCopy Anchor Link

List cluster events across every cluster in the active organization.

Authorization

Query Parameters

Response Body

`application/json`

`application/problem+json`

List clusters in the active organization, optionally with a fleet summary.

Authorization

Query Parameters

Response Body

`application/json`

`application/problem+json`

Create a cluster and issue its install command.

Authorization

Request Body

Response Body

`application/json`

`application/problem+json`

Get the public key SSH installs sign in with, creating it on first use.

Authorization

Response Body

`application/json`

`application/problem+json`

Get one cluster.

Authorization

Path Parameters

Response Body

`application/json`

`application/problem+json`

Rename a cluster, or cordon/uncordon every node in it.

Authorization

Path Parameters

Request Body

Response Body

`application/json`

`application/problem+json`

Remove a cluster after every environment is unbound.

Authorization

Path Parameters

Response Body

`application/problem+json`

Get a cluster's agent update status and history.

Authorization

Path Parameters

Response Body

`application/json`

`application/problem+json`

Roll a cluster's agent back to an image it has already run.

Authorization

Path Parameters

Request Body

Response Body

`application/json`

`application/problem+json`

Update a cluster's agent to a new image, defaulting to the control plane's own.

Authorization

Path Parameters

Request Body

Response Body

`application/json`

`application/problem+json`

Issue the command that installs CloudNativePG, cert-manager and the Barman Cloud Plugin on this cluster.

Authorization

Path Parameters

Response Body

`application/json`

`application/problem+json`

Replace a cluster's single-use enrollment token.

Authorization

Path Parameters

Response Body

`application/json`

`application/problem+json`

List a cluster's most recent events.

Authorization

Path Parameters

Query Parameters

Response Body

`application/json`

`application/problem+json`