Fleet

Which hosts running the certificate agent are about to break, and why.

Without this the only way to know is to ssh into each machine and read its logs, which stops working past a handful of hosts.

Check in#

1

POST /api/v1/fleet/checkin

Called by the agent after every run. Requires any authenticated identity — no special scope.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "fqdn": "web01.example.com",
  "agent_version": "1.0.0",
  "status": "ok",
  "certificates": [
    {
      "path": "hosts/web01.example.com/www.example.com",
      "not_after": "2026-11-04T10:22:31Z",
      "mode": "csr",
      "last_deployed_at": "2026-08-11T09:14:02Z"
    }
  ]
}

status is ok, partial or error, mirroring the agent's exit code.

The record is keyed on the authenticated service account, not the hostname. A host can therefore only ever overwrite its own record, regardless of the name it claims — the hostname is self-asserted and is not a trust boundary.

Fleet status#

1

GET /api/v1/fleet/status

Requires service_accounts:read.

1
2
3
4
5
6
7
8
9

{
  "hosts_total": 12,
  "certificates_total": 31,
  "hosts_silent":  [{"fqdn": "web07", "hours_silent": 74.2}],
  "hosts_failing": [{"fqdn": "lb01", "status": "partial", "error": "reload hook failed"}],
  "certificates_expiring": [{"fqdn": "mail01", "path": "…", "days_left": 4, "expired": false}],
  "healthy": false,
  "thresholds": {"stale_after_hours": 36, "expiry_window_days": 21}
}

The three failure modes are deliberately separate#

hosts_silent — hosts that have stopped reporting. This is the dangerous one: a silent host looks exactly like a healthy host right up until its certificate expires, because absence of bad news is not good news. Causes include the timer being disabled, the machine being decommissioned without anyone saying so, or its key being revoked.

hosts_failing — hosts that reported a problem. Renewal or a reload hook failed. The certificate on disk may still be valid, so this is usually less urgent than it looks, but it means the host is no longer self-healing.

certificates_expiring — certificates inside the reporting window, most urgent first. The window (21 days) is deliberately narrower than the agent's own 30-day renewal threshold, so a certificate only appears here if renewal has actually failed, rather than merely being due.

healthy is a single boolean an alert can key on — false when any host is silent or failing, or any certificate is within seven days — so the "is this bad?" judgement is not reimplemented in three dashboards.

Both thresholds are tunable per request:

1

GET /api/v1/fleet/status?stale_after_hours=48&expiry_window_days=14

stale_after_hours defaults to 36, allowing a full missed cycle of the twice-daily timer plus slack.

Host list#

1

GET /api/v1/fleet/hosts

Requires service_accounts:read. Every agent host, most recently seen first, with its version, source IP, last run status and the certificates it manages.

Opting out#

Set report_status = false under [agent] in the agent config. A check-in failure never affects renewal — by the time it runs the certificates are already deployed and the services reloaded, so reporting is a monitoring concern, not a renewal one.

What's next#

• Certificate Agent — what reports here.
• Enrollment — how hosts get the credential they report with.