Agent

The endpoints a cluster's agent and the install scripts call. They authenticate with agent and enrollment tokens, not with API tokens. Each operation lists its method and path, parameters, request body, responses and an example call.

Fetch the authenticated cluster's database-authorized namespace and agent-image policy.

GET/agent/v1/access-state

Header Parameters

Authorization?string

Bearer RBAC broker token.

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/agent/v1/access-state"

{  "$schema": "https://example.com/AccessState.json",  "buildRegistry": true,  "desiredAgentImage": "string",  "environments": [    {      "id": "string",      "namespace": "string",      "podSecurityBaseline": true    }  ],  "revision": 0}

Claim privileged commands for this cluster's access broker.

GET/agent/v1/broker-commands

Header Parameters

Authorization?string

Bearer broker token. The normal agent token is not accepted.

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/agent/v1/broker-commands"

{  "$schema": "https://example.com/BrokerCommands.json",  "commands": [    {      "expiresAt": "2019-08-24T14:15:22Z",      "id": "string",      "kind": "string",      "node": "string"    }  ]}

Acknowledge one privileged command for this cluster.

POST/agent/v1/broker-events

Header Parameters

Authorization?string

Bearer broker token. The normal agent token is not accepted.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

error?string

id*string

joinToken?string

joinTokenExpiresAt?string

Formatdate-time

Response Body

`application/problem+json`

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

Empty

Ship a batch of a build's log lines.

POST/agent/v1/build-logs

Header Parameters

Authorization?string

Bearer agent token.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

buildId*string

lines*array<>|null

Response Body

`application/problem+json`

curl -X POST "https://example.com/agent/v1/build-logs" \  -H "Content-Type: application/json" \  -d '{    "buildId": "string",    "lines": [      {        "at": "2019-08-24T14:15:22Z",        "text": "string"      }    ]  }'

Empty

Render the shell script that installs CloudNativePG, cert-manager and the Barman Cloud Plugin on an already-installed cluster.

POST/agent/v1/cnpg.sh

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

token*string

Single-use token authorizing this script.

Response Body

`application/json`

`application/problem+json`

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

"string"

Render the shell script that retrofits the cluster's existing single server to an etcd-backed datastore in place.

POST/agent/v1/enable-ha.sh

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

token*string

Single-use token authorizing this script.

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/agent/v1/enable-ha.sh" \  -H "Content-Type: application/json" \  -d '{    "token": "string"  }'

"string"

Exchange a single-use enrollment token for a permanent agent token.

POST/agent/v1/enroll

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

enrollmentToken*string

hello*

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/agent/v1/enroll" \  -H "Content-Type: application/json" \  -d '{    "enrollmentToken": "string",    "hello": {      "agentVersion": "string",      "capabilities": {        "metricsServer": true,        "tailscale": true,        "traefik": true      },      "k3sVersion": "string",      "nodes": [        {          "allocatable": {            "cpuMilli": 0,            "ephemeralBytes": 0,            "memoryBytes": 0,            "pods": 0          },          "allocated": {            "cpuMilli": 0,            "ephemeralBytes": 0,            "memoryBytes": 0,            "pods": 0          },          "k3sVersion": "string",          "name": "string",          "ready": true,          "unschedulable": true        }      ]    }  }'

{  "$schema": "https://example.com/EnrollResponse.json",  "agentToken": "string",  "clusterId": "string"}

Report a batch of cluster events: release stage changes, pod/node observations, drift.

POST/agent/v1/events

Header Parameters

Authorization?string

Bearer agent token.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

[index: integer]?

Response Body

`application/problem+json`

curl -X POST "https://example.com/agent/v1/events" \  -H "Content-Type: application/json" \  -d '[    {      "at": "2019-08-24T14:15:22Z",      "kind": "string"    }  ]'

Empty

Report cluster and node health, applied revision and pod metrics.

POST/agent/v1/heartbeat

Header Parameters

Authorization?string

Bearer agent token.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

appliedRevision*integer

Formatint64

at*string

Formatdate-time

capabilities*

cronRuns?array<>|null

kindMetrics?array<>|null

nodes*array<>|null

postgres?array<>|null

reconcileError?string

traffic?array<>|null

volumes?array<>|null

workloads*array<>|null

Response Body

`application/problem+json`

curl -X POST "https://example.com/agent/v1/heartbeat" \  -H "Content-Type: application/json" \  -d '{    "appliedRevision": 0,    "at": "2019-08-24T14:15:22Z",    "capabilities": {      "metricsServer": true,      "tailscale": true,      "traefik": true    },    "nodes": [      {        "allocatable": {          "cpuMilli": 0,          "ephemeralBytes": 0,          "memoryBytes": 0,          "pods": 0        },        "allocated": {          "cpuMilli": 0,          "ephemeralBytes": 0,          "memoryBytes": 0,          "pods": 0        },        "k3sVersion": "string",        "name": "string",        "ready": true,        "unschedulable": true      }    ],    "workloads": [      {        "environmentId": "string",        "pods": [          {            "cpuMilli": 0,            "memoryBytes": 0,            "name": "string",            "node": "string",            "phase": "string",            "ready": true,            "restarts": 0          }        ],        "releaseId": "string",        "serviceId": "string"      }    ]  }'

Empty

Report the agent's identity, versions and running image on every stream connection.

POST/agent/v1/hello

Header Parameters

Authorization?string

Bearer agent token.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

agentImage?string

agentVersion*string

apiServerUrl?string

capabilities*

k3sVersion*string

nodes*array<>|null

Response Body

`application/problem+json`

curl -X POST "https://example.com/agent/v1/hello" \  -H "Content-Type: application/json" \  -d '{    "agentVersion": "string",    "capabilities": {      "metricsServer": true,      "tailscale": true,      "traefik": true    },    "k3sVersion": "string",    "nodes": [      {        "allocatable": {          "cpuMilli": 0,          "ephemeralBytes": 0,          "memoryBytes": 0,          "pods": 0        },        "allocated": {          "cpuMilli": 0,          "ephemeralBytes": 0,          "memoryBytes": 0,          "pods": 0        },        "k3sVersion": "string",        "name": "string",        "ready": true,        "unschedulable": true      }    ]  }'

Empty

Render the shell script that takes over a fresh server: installs K3s, hardens it, and starts the agent.

POST/agent/v1/install.sh

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

token*string

Single-use token authorizing this script.

Response Body

`application/json`

`application/problem+json`

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

"string"

Consume a node join token and fetch a short-lived K3s worker credential minted by the cluster access broker.

POST/agent/v1/install/join-config

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

token*string

Node join token. Single use: consumed by this call.

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/agent/v1/install/join-config" \  -H "Content-Type: application/json" \  -d '{    "token": "string"  }'

{  "$schema": "https://example.com/JoinConfigBody.json",  "k3sVersion": "string",  "serverUrl": "string",  "token": "string"}

Render the Kubernetes manifest that installs the cluster agent and RBAC broker.

POST/agent/v1/install/manifest

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

token*string

Single-use enrollment token, from POST /api/v1/clusters.

Response Body

`application/json`

`application/problem+json`

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

"string"

Report one step of one node's install or host-script run.

POST/agent/v1/install/progress

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

logTail?string

Trailing excerpt of the step's log; truncated server-side to 8 KiB.

message?string

nodeName*string

hostname -s of the node reporting, e.g. from install.sh.

Length1 <= length

serverUrl?string

The server's reachable URL; accepted only with step "k3s" from a server-role token.

status*string

Value in

"running"
"done"
"failed"
"skipped"

step*string

Value in

"preflight"
"packages"
"sysctl"
"mesh"
"k3s"
"firewall"
"ssh"
"fail2ban"
"updates"
"agent"
"join"
"etcd"
"cnpg"

token*string

Short-lived progress-only credential embedded in the rendered script.

Response Body

`application/problem+json`

curl -X POST "https://example.com/agent/v1/install/progress" \  -H "Content-Type: application/json" \  -d '{    "nodeName": "string",    "status": "running",    "step": "preflight",    "token": "string"  }'

Empty

Ship a batch of container log lines.

POST/agent/v1/logs

Header Parameters

Authorization?string

Bearer agent token.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

dropped?integer

Formatint64

lines*array<>|null

Response Body

`application/problem+json`

curl -X POST "https://example.com/agent/v1/logs" \  -H "Content-Type: application/json" \  -d '{    "lines": [      {        "at": "2019-08-24T14:15:22Z",        "environmentId": "string",        "podName": "string",        "processName": "string",        "serviceId": "string",        "text": "string"      }    ]  }'

Empty

Prove the caller can reach and authenticate to the control plane.

GET/agent/v1/ping

Header Parameters

Authorization?string

Bearer agent token.

Response Body

`application/problem+json`

curl -X GET "https://example.com/agent/v1/ping"

Empty

Stream desired state and out-of-band commands to a connected cluster agent.

GET/agent/v1/stream

Header Parameters

Authorization?string

Bearer agent token.

Response Body

`text/event-stream`

`application/problem+json`

curl -X GET "https://example.com/agent/v1/stream"

[  {    "data": {      "$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"        }      }    },    "event": "command",    "id": 0,    "retry": 0  }]

Render the shell script that installs the Tailscale Kubernetes operator and creates the cluster's egress ProxyGroup.

POST/agent/v1/tailscale.sh

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

token*string

Single-use token authorizing this script.

Response Body

`application/json`

`application/problem+json`

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

"string"

Agent

Fetch the authenticated cluster's database-authorized namespace and agent-image policy.Copy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

Claim privileged commands for this cluster's access broker.Copy Anchor Link

Header ParametersCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

Acknowledge one privileged command for this cluster.Copy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

204

defaultapplication/problem+json

Ship a batch of a build's log lines.Copy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

204

defaultapplication/problem+json

Render the shell script that installs CloudNativePG, cert-manager and the Barman Cloud Plugin on an already-installed cluster.Copy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

Render the shell script that retrofits the cluster's existing single server to an etcd-backed datastore in place.Copy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

Exchange a single-use enrollment token for a permanent agent token.Copy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

Report a batch of cluster events: release stage changes, pod/node observations, drift.Copy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

204

defaultapplication/problem+json

Report cluster and node health, applied revision and pod metrics.Copy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

204

defaultapplication/problem+json

Report the agent's identity, versions and running image on every stream connection.Copy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

204

defaultapplication/problem+json

Render the shell script that takes over a fresh server: installs K3s, hardens it, and starts the agent.Copy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

Consume a node join token and fetch a short-lived K3s worker credential minted by the cluster access broker.Copy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

Render the Kubernetes manifest that installs the cluster agent and RBAC broker.Copy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

defaultapplication/problem+json

Report one step of one node's install or host-script run.Copy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

204

defaultapplication/problem+json

Ship a batch of container log lines.Copy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Fetch the authenticated cluster's database-authorized namespace and agent-image policy.

Header Parameters

Response Body

`application/json`

`application/problem+json`

Claim privileged commands for this cluster's access broker.

Header Parameters

Response Body

`application/json`

`application/problem+json`

Acknowledge one privileged command for this cluster.

Header Parameters

Request Body

Response Body

`application/problem+json`

Ship a batch of a build's log lines.

Header Parameters

Request Body

Response Body

`application/problem+json`

Render the shell script that installs CloudNativePG, cert-manager and the Barman Cloud Plugin on an already-installed cluster.

Request Body

Response Body

`application/json`

`application/problem+json`

Render the shell script that retrofits the cluster's existing single server to an etcd-backed datastore in place.

Request Body

Response Body

`application/json`

`application/problem+json`

Exchange a single-use enrollment token for a permanent agent token.

Request Body

Response Body

`application/json`

`application/problem+json`

Report a batch of cluster events: release stage changes, pod/node observations, drift.

Header Parameters

Request Body

Response Body

`application/problem+json`

Report cluster and node health, applied revision and pod metrics.

Header Parameters

Request Body

Response Body

`application/problem+json`

Report the agent's identity, versions and running image on every stream connection.

Header Parameters

Request Body

Response Body

`application/problem+json`

Render the shell script that takes over a fresh server: installs K3s, hardens it, and starts the agent.

Request Body

Response Body

`application/json`

`application/problem+json`

Consume a node join token and fetch a short-lived K3s worker credential minted by the cluster access broker.

Request Body

Response Body

`application/json`

`application/problem+json`

Render the Kubernetes manifest that installs the cluster agent and RBAC broker.

Request Body

Response Body

`application/json`

`application/problem+json`

Report one step of one node's install or host-script run.

Request Body

Response Body

`application/problem+json`

Ship a batch of container log lines.

Header Parameters

Request Body

Response Body

`application/problem+json`

Prove the caller can reach and authenticate to the control plane.

Header Parameters

Response Body

`application/problem+json`

Stream desired state and out-of-band commands to a connected cluster agent.

Header Parameters