Skip to content

Pinggy

Enrolling nodes

Enrolling a node, how the control plane places monitors on it, and node health.

What a node is

A monitoring node is a separate binary from the control plane. It never connects to PostgreSQL and never receives an inbound connection: it polls the control plane over outbound HTTPS for the checks assigned to it, executes them, and submits results. A node's administrator-assigned region, site, provider, capacity, and lifecycle cannot be changed by the node's own credential — only an operator, from the control plane, changes those.

Enrolling a node

  1. Create the node from the authenticated /nodes page, or POST /api/nodes with a browser session and a CSRF token. The response carries a one-time enrollment token.
  2. Start the node binary with that token and a credential file path. On first start it exchanges the one-time token for a durable credential and writes it to the credential file, with file mode 0600.
  3. On every start after that, the node reads its durable credential from the same file and the one-time token is no longer needed.

A node requires only outbound access to the control plane; it needs no inbound port and no PostgreSQL access at all.

Node health

A node's health is derived entirely from how recently the control plane received a heartbeat from it — never from what the node reports about itself:

HealthMeaning
PENDINGNot yet enrolled, or never yet seen.
ONLINEA heartbeat was received within the freshness threshold.
STALENo heartbeat within the freshness threshold, but within the offline threshold — assignments are retained during this grace period.
OFFLINENo heartbeat within the offline threshold.
DRAININGAn operator has asked the node's assignments to be moved elsewhere.
DISABLEDAn operator has turned the node off; it is not eligible for new work.
REVOKEDThe node's credential has been revoked.

The default freshness threshold is 45 seconds and the default offline threshold is 5 minutes. STALE, OFFLINE, DISABLED, and REVOKED nodes are all ineligible for new placement; a STALE node keeps the assignments it already had until it either returns or crosses into OFFLINE. A node that returns after being OFFLINE is not automatically reclaimed back onto — placement is recomputed on its own schedule, not forced by a node reappearing.

Node health is a platform-health fact, distinct from a monitor's own consensus state — see States for why Pinggy keeps the two separate. A node going OFFLINE reduces the assigned replicas available to every monitor placed on it, which can move those monitors into under-replication — but it does not, by itself, make any of them UNKNOWN.

Placement

When a monitor is created, the control plane places it on the number of nodes its assurance level desires, chosen from the eligible, healthy nodes with the most available capacity, spread across distinct sites, regions, and providers where the fleet allows it. Placement is transactional and reconciled on a running interval, so a node going offline or a monitor's assurance level changing is picked up automatically rather than requiring a manual rebalance.

If the fleet has no eligible capacity for a monitor's desired replicas, the monitor remains present, explicitly capacity-blocked, until reconciliation observes restored capacity — it is never silently left unmonitored without that fact being stated. See Coverage.

This article is part of this repository and is served by the same binary, so what you read here is the documentation for the version you are running.