Cluster API
Cluster membership, mesh0, certificate, and node
lifecycle operations. The routes are split across several router files
under modules/cluster/ (ce module; ee overlays in modules/cluster/) and mounted on one chi sub-router by
buildRouter in router.go.
Hand-maintained notes against modules/cluster/*_router.go (ce module). Route inventory (generated): routes.md. Response models (generated): response-models/cluster.md.
Public method routes (/api/method)
Section titled “Public method routes (/api/method)”| Method | Path | Source |
|---|---|---|
POST | /api/method/shc.cluster.token | token_router.go |
GET | /api/method/shc.cluster.status | nodes_router.go |
GET | /api/method/shc.cluster.nodes | nodes_router.go |
GET | /api/method/shc.node.ls | nodes_router.go |
GET | /api/method/shc.node.status | nodes_router.go |
GET | /api/method/shc.cluster.ping | admin_router.go |
POST | /api/method/shc.cluster.repair | admin_router.go |
DELETE | /api/method/shc.cluster.rm | admin_router.go |
GET | /api/method/shc.cluster.logs | admin_router.go |
POST | /api/method/shc.cluster.leave | lifecycle_router.go |
POST | /api/method/shc.cluster.drain | lifecycle_router.go |
POST | /api/method/shc.cluster.forget | lifecycle_router.go |
POST | /api/method/shc.cluster.force_leader | lifecycle_router.go |
GET | /api/method/shc.cluster.certs.list | certs_router.go |
POST | /api/method/shc.cluster.certs.rotate | certs_router.go |
POST | /api/method/shc.cluster.certs.rotate_now | certs_router.go |
POST | /api/method/shc.cluster.mesh.client.enrol | mesh_client_router.go |
GET | /api/method/shc.cluster.mesh.client.ls | mesh_client_router.go |
GET | /api/method/shc.cluster.mesh.client.peers | mesh_client_router.go |
POST | /api/method/shc.cluster.mesh.client.revoke | mesh_client_router.go |
GET | /api/method/shc.cluster.mesh.status | mesh_router.go |
GET | /api/method/shc.cluster.mesh.diagnose | mesh_router.go |
shc.cluster.nodes, shc.node.ls, shc.node.status, shc.cluster.certs.list, shc.cluster.fabric.status, shc.cluster.ping and shc.cluster.logs take platform:manage. shc.cluster.status takes tenant:read, because the console title bar polls it; below platform the answer carries only cluster_name, the node counts, voters, required_voters and quorum_healthy (SHC-924 ruling). routes.md holds every route’s gate.
Node enrolment is POST /api/join/node.enroll on the public listener.
Traefik’s shc-api router reaches that listener on 443. Source
modules/internal_rpc/join.go. The generated inventory lists it as
POST /api/join/{function_name}.
Internal RPC functions
Section titled “Internal RPC functions”Peer certificate functions served through POST /internal/rpc/{function}
on the internal listener, source certs_rpc.go:
| Function | Purpose |
|---|---|
certs.info | Report this node’s cert files: presence, expiry, subject, issuing key id, fingerprints |
certs.rotate | Re-sign the calling node’s leaf, identified by its verified client certificate |
certs.renew | Re-issue this node’s own leaf off the current cluster CA and hot-reload the listener |
Selected route details
Section titled “Selected route details”POST /api/method/shc.cluster.token
Section titled “POST /api/method/shc.cluster.token”- summary: mint a cluster join token.
GET /api/method/shc.cluster.ping
Section titled “GET /api/method/shc.cluster.ping”- summary: per-node TCP probe of every registered member.
- query params:
node,count,timeout
POST /api/method/shc.cluster.repair
Section titled “POST /api/method/shc.cluster.repair”- summary: sweep unreachable / stale members (tidy).
--force(force_leader) is the destructive escalation when a removal would break quorum. - body:
{ dry_run, verbose, yes }(all optional)
DELETE /api/method/shc.cluster.rm
Section titled “DELETE /api/method/shc.cluster.rm”- summary: remove a node from the cluster.
- query params:
node(required),force
GET /api/method/shc.cluster.logs
Section titled “GET /api/method/shc.cluster.logs”- summary: tail a daemon log file.
- query params:
service(required, bare filename),node,lines
Mesh (shc.cluster.mesh.*)
Section titled “Mesh (shc.cluster.mesh.*)”There is no enable and no disable. mesh0 is the node plane, a kernel
WireGuard device, and a multi-node cluster runs it from the first join.
status returns whether this node’s mesh0 is up and one row per node
(mesh_address, installed, running). diagnose probes each peer’s internal
API over mesh0. mesh.client.enrol, ls, peers and revoke join an
operator CLI onto mesh0 through a gateway node.