Nomad Cluster
A read-only inventory of a HashiCorp Nomad cluster from one call against the Nomad HTTP API: every job with its scheduling status and allocation rollup, every client node with its readiness and drain state, and cluster-wide health counts.
"Is anything failing on the cluster?" has a citable answer sitting behind two Nomad endpoints — /v1/jobs and /v1/nodes. This model reads both, joins them in memory, and hands back each job's allocation totals (queued, running, failed, lost) and each node's healthy flag (ready, eligible, not draining), plus rollups: runningJobs, jobsWithFailures, readyNodes, unhealthyNodes, and a single hasProblems boolean.
The guarantee
The Nomad address is always supplied by the caller — no cluster, namespace, or datacenter is baked in. Once that address is parsed, every request is pinned to its exact origin (scheme + host + port), re-checked after any redirect, so a 302 cannot walk the run off your Nomad agent onto another host. That host-lock is the reason this is an extension model and not a shell step wrapping curl against a caller-supplied URL.
Honesty over false calm
The two endpoints are read independently. If nodes list but jobs do not (or vice versa), the snapshot does not report an all-clear on the half it could not see — it sets jobsChecked / nodesChecked to false and says so in notes. A page that fails after retries sets the section's truncated flag, so a partial list can never be mistaken for a complete one.
Method
- inventory — one fan-out call: page
/v1/jobs(for one namespace or all with*) and/v1/nodes, join them, and emit a singlesnapshotresource. Supports an optional region and a per-section result limit.
Design notes
Nomad needs a token only when ACLs are enabled. The token is optional and, when supplied, comes from the model definition via a vault expression (sent as X-Nomad-Token) — never hardcoded. Sending a token over plaintext HTTP leaks it, so the model warns when a token is paired with an http:// address. Requests retry 429/5xx with backoff and honour Retry-After.
Read-only throughout: it only ever lists jobs and nodes.
Quick Start
swamp extension pull @hmcrum/nomad-cluster
swamp model create @hmcrum/nomad-cluster nomad \
--input address=https://nomad.example.com:4646
swamp model method run nomad inventory swamp model method run nomad inventory --input namespace=default
swamp data get nomad snapshot --json ```Global Arguments
| Argument | Type | Description |
|---|---|---|
| address | string | Base address of the Nomad HTTP API, origin only (scheme://host:port), e.g. https://nomad.example.com:4646. Defaults to Nomad's local plaintext address. |
| apiToken | string | Optional Nomad ACL token (SecretID). Only needed when ACLs are enabled. Supply via a vault expression, never hardcoded. Sent as the X-Nomad-Token header. |
| region | string | Optional Nomad region to target. Empty uses the agent's own region. |
| Argument | Type | Description |
|---|---|---|
| namespace | string | Nomad namespace to list jobs in; '*' lists all authorized namespaces (the default). Does not affect nodes, which are cluster-wide. |
| limit | number | Maximum jobs (and, separately, nodes) to return |
| pageSize | number | Nomad per_page size for each list request |
| paceMs | number | Milliseconds to wait between paged requests |
Resources
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned