Node Management

Supporting a mesh means knowing its nodes: who they are, what they serve, and what policy they currently match. The node API exists to make that knowledge immediate.

Node inventory

Node APIs should expose the state operators actually need: identity, routes, tags, ACL matches, relay status, service bindings, and the last telemetry heartbeat. With those fields, a support question — "why can't this host reach that service?" — becomes a lookup, not an investigation.

Representative node record

  GET /v1/nodes/<id>

  {
    "id": "node_01J2...",
    "name": "node-a.rizoma.mesh",
    "address": "100.64.0.1/32",
    "tags": ["control-plane", "production"],
    "routes": ["100.64.0.0/10 via node-a"],
    "relay": "relay-eu-1",
    "services": ["coordinator", "webpanel"],
    "heartbeat": "2026-08-18T09:40:58Z",
    "acl_matches": ["operations -> control plane"]
  }

Policy posture

Posture is not just "is the node up" — it is what the node is allowed to do right now. The ACL match field ties the inventory to the policy model: you can see which grants apply to a node and compare that against what it is actually doing. A mismatch between posture and behavior is a policy bug or an incident in progress.

Telemetry and heartbeat

Agents publish their heartbeat continuously: endpoints, E2E key material, telemetry, and command results — and receive back peers, relay selection, ACL sync, and ingress assignments. The heartbeat is the mesh's nervous system: a node whose heartbeat is stale is a node the control plane cannot reason about, and should be treated as such in policy and in alerts.

Checking node health

  # health/readiness/info + Prometheus metrics, per component
  curl http://node-a.rizoma.mesh:8080/healthz
  curl http://node-a.rizoma.mesh:8080/readyz
  curl http://node-a.rizoma.mesh:8080/metrics | grep mesh_node

Operations that stay close to topology

Keep node operations close to the real mesh topology: enroll, re-key, re-tag, move a relay assignment, drain an ingress — each operation should be expressible against the coordinator and verified through the heartbeat. When support work happens against the same API the mesh uses internally, the documentation, the tooling, and the mesh never disagree.

Node lifecycle and certification. The Operator certification covers enrollment, inventory, and policy posture end to end — a practical way to prove the team can run node operations before it is on call for them.

Previous API Authentication Next Audit Webhooks