Skip to content
SHC Docs

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.

MethodPathSource
POST/api/method/shc.cluster.tokentoken_router.go
GET/api/method/shc.cluster.statusnodes_router.go
GET/api/method/shc.cluster.nodesnodes_router.go
GET/api/method/shc.node.lsnodes_router.go
GET/api/method/shc.node.statusnodes_router.go
GET/api/method/shc.cluster.pingadmin_router.go
POST/api/method/shc.cluster.repairadmin_router.go
DELETE/api/method/shc.cluster.rmadmin_router.go
GET/api/method/shc.cluster.logsadmin_router.go
POST/api/method/shc.cluster.leavelifecycle_router.go
POST/api/method/shc.cluster.drainlifecycle_router.go
POST/api/method/shc.cluster.forgetlifecycle_router.go
POST/api/method/shc.cluster.force_leaderlifecycle_router.go
GET/api/method/shc.cluster.certs.listcerts_router.go
POST/api/method/shc.cluster.certs.rotatecerts_router.go
POST/api/method/shc.cluster.certs.rotate_nowcerts_router.go
POST/api/method/shc.cluster.mesh.client.enrolmesh_client_router.go
GET/api/method/shc.cluster.mesh.client.lsmesh_client_router.go
GET/api/method/shc.cluster.mesh.client.peersmesh_client_router.go
POST/api/method/shc.cluster.mesh.client.revokemesh_client_router.go
GET/api/method/shc.cluster.mesh.statusmesh_router.go
GET/api/method/shc.cluster.mesh.diagnosemesh_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}.

Peer certificate functions served through POST /internal/rpc/{function} on the internal listener, source certs_rpc.go:

FunctionPurpose
certs.infoReport this node’s cert files: presence, expiry, subject, issuing key id, fingerprints
certs.rotateRe-sign the calling node’s leaf, identified by its verified client certificate
certs.renewRe-issue this node’s own leaf off the current cluster CA and hot-reload the listener
  • summary: mint a cluster join token.
  • summary: per-node TCP probe of every registered member.
  • query params: node, count, timeout
  • 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)
  • summary: remove a node from the cluster.
  • query params: node (required), force
  • summary: tail a daemon log file.
  • query params: service (required, bare filename), node, lines

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.