Fleet Health

Documentation Index

Fetch the complete documentation index at: https://www.halite-app.com/llms.txt

Use this file to discover all available pages before exploring further.

The Fleet Health page shows the compliance state of every minion in your Salt fleet, tracks compliance over time, and surfaces the states that fail most often across the fleet. It is driven entirely by ingested state.highstate (and related state function) results — no live Salt connection is needed to view the dashboard.

​

Health statuses

Each minion has exactly one health status, derived from its most recent ingested run and its current online/offline state. The status values (from HealthStatus in fleet/schemas.py) are:

​

API endpoints

​

GET /api/fleet/health

Returns the full fleet health snapshot as a FleetHealthOut list. Requires an authenticated session. Each row in minions contains: Connected-minion presence comes from the fleet scheduler’s cached manage.present result. On cold start (before the scheduler has ticked), the endpoint falls back to the set of minions with at least one ingested run.

​

GET /api/fleet/compliance

Returns a compliance time series (oldest-first) for charting. Use the limit parameter to control how many recent runs are included (1–200, default 30). Each bucket corresponds to one highstate JID aggregated across all minions:

​

GET /api/fleet/top-failures

Returns the states that have failed most often across the most recent run per minion. Use limit to control how many entries are returned (1–50, default 10). Each entry contains:

​

GET /api/fleet/runs/{run_id}

Returns the full detail for a single ingested highstate run by its database UUID. The response includes the raw state.highstate return dictionary alongside the summarised counts.

​

How highstate runs are ingested

The fleet scheduler polls for recent state.* jobs by reading the jobs_index table for JIDs whose started_at is within the configured lookback window. For each new JID found it calls runner.jobs.list_job on the Salt master and stores per-minion results. The parser (fleet/parser.py) validates each minion’s return against the Salt lowstate key pattern (module_|-state_id_|-name_|-fun). Runs where the minion returned a “did not return” string sentinel are stored with blocked = True and zero counts. Runs that cannot be parsed as a valid lowstate dict are silently skipped. Ingestion is idempotent on (minion_id, jid) — re-processing the same JID does not create duplicate rows.

​

Example: investigating a failing state

​

Permissions

All fleet endpoints require an authenticated session only — there is no additional require_perm call on any fleet route. Any logged-in Halite user can view fleet health data.