Nodes

Register a new worker node or reconnect an existing one

post/internal/nodes/register

Request

  • Base URL: /api (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/internal/nodes/register
  • Auth: none declared

Request body

addressstring required

Node's reachable address (e.g., "10.100.0.2" or "192.168.1.50")

architecturestring nullable

Container platform of this node's Docker daemon (linux/amd64, linux/arm64). Optional: agents older than multi-arch support omit it and the value is learned from the first heartbeat instead.

csr_pemstring nullable

Node-generated certificate signing request (PEM) for multi-node mTLS (ADR-020 WS-2.1). When present, the control plane signs it with the cluster CA and returns the leaf + CA cert. Optional — token-only nodes (legacy / edge) still register without one.

edge_public_keystring nullable

X25519 public key for ECIES certificate encryption (base64-encoded, edge nodes only)

join_tokenstring nullable

Join token to authorize this registration (must match the token generated in Settings)

labelsunknown
namestring required

Unique name for this node

prior_tokenstring nullable

The node's current token, supplied to prove possession when re-registering (changing the identity of) a node that already exists. Optional; only needed to rebind a still-live node. (ADR-020 WS-1.2.)

private_addressstring required

Private/WireGuard address for inter-node communication

public_endpointstring nullable

Public endpoint for WireGuard (e.g., "203.0.113.1:51820")

rolestring nullable

Node role (default: "worker")

tokenstring required

Registration token (plaintext, will be hashed before storage)

wg_public_keystring nullable

WireGuard public key

Response

Node reconnected successfully

ca_cert_pemstring nullable

The cluster CA certificate (PEM) the node pins as its trust root. Present only when a csr_pem was supplied. (ADR-020 WS-2.1.)

cert_pemstring nullable

The signed per-node leaf certificate (PEM) the agent serves as its TLS server cert. Present only when a csr_pem was supplied. (ADR-020 WS-2.1.)

idinteger required
messagestring required
mtls_requiredboolean required

Whether this node must serve mTLS and reject plaintext agent traffic.

namestring required
statusstring required

Changes

No recorded changes to this operation across all 53 revisions of this API.