Skip to content
StratumStratum Docs

List every service's resource limits and fleet convergence state.

GET
/v1/admin/substrate/resources
Code sample: Shell / cURL
curl --request GET \
  --url https://stratum.example.com/v1/admin/substrate/resources \
  --header 'Authorization: Bearer <token>'

Bootstrap-admin endpoint returning one row per cappable service — every substrate quadlet plus the two tenant data planes — with its effective cap, how many nodes report it, how many have drifted, how many carry a cap awaiting a restart, and how much headroom sits between the cap and the observed peak.

headroomPct is the column that matters when deciding what to change: it is the tightest services, not the largest ones, that a cap change puts at risk. On cl-ucousbfs vminsert sits at 51% of its 512m cap while axdnsd sits at 2% of 1g.

Cedar action: substrate:ListServiceResources.

Authorizations

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”

One row per service.

Media typeapplication/json

Fleet-wide resource-limit summary, one row per service.

object
items
required
Array<object>

One service’s fleet summary, for the admin console’s table.

object
serviceName
required
string
effective
required

One service’s resolved caps, with the scope that supplied each value so an operator can see where to change it.

object
serviceName
required
string
nodeId

The node this was resolved for. Absent for an install-wide answer.

string
memoryMax
required

Podman --memory value.

string
cpuQuota
required

Podman --cpus value.

string
memorySource
required

Which scope supplied memoryMax. default is the compiled catalog.

string
Allowed values: node install default
cpuSource
required

Which scope supplied cpuQuota.

string
Allowed values: node install default
restart
required

How a change to this service is applied on a node. immediate — the converger writes the quadlet, reloads systemd and restarts the unit itself. deferred — it writes and reloads, then reports pendingRestart and stops, because restarting this service is itself a cluster-wide event (the control plane’s restart kills IMDS fleet-wide; Postgres’s is a Patroni failover). The new cap applies at the next restart, which an operator sequences.

string
Allowed values: immediate deferred
observedPeakBytes

The compiled measurement the default was derived from.

integer format: int64
why

What the default number is doing and where it came from.

string
nodesReporting
required

How many nodes have reported on this service. Compare against the cluster’s node count — a service reporting on fewer nodes than exist is one the converger is not running for everywhere.

integer
nodesDrifted
required

Nodes whose rendered quadlet disagrees with what they resolved.

integer
nodesPendingRestart
required

Nodes carrying a new cap on disk that takes effect at the next restart.

integer
observedPeakBytes

The highest cgroup memory.peak any node reported.

integer format: int64
observedCurrentBytes

The highest cgroup memory.current any node reported — present usage, aggregated as the fleet maximum exactly as the peak is, so a busy replica is not averaged away by idle ones. 0 when nothing has been observed.

integer format: int64
headroomPct
required

How far the effective cap sits above the observed peak, as a percentage. -1 when nothing has been observed to compare against. Surfaced so the tightest service in the estate is visible directly rather than requiring arithmetic on two other columns.

integer
dataPlane
required
boolean
applicability
required

Whether this service is expected to report node status on this install, and if not, why not.

Without it, four rows on the admin resource-limits page rendered identically — no peak, no node count, nodesReporting: 0 — for three different reasons, only one of which is a problem. The one state an operator needs to notice was indistinguishable from two that are entirely normal, so no alarm could be written against it.

  • expected — this install renders the service and every node should be reporting it. Zero reporters here is a fault: the host-helper is down, the converger never ran, the intent was never published, or the node is unreachable.
  • data-plane — a per-VPC or per-load-balancer pod, created imperatively by the sweeper rather than rendered as a quadlet. It reports an observation (observedPeakBytes / observedCurrentBytes, sampled from the pod’s own cgroup) on whichever nodes currently host one, and never reports drift there is no rendered file to compare and its cap reaches the pod through the sweeper. nodesReporting: 0 here means no pod is placed on any node, which is placement doing its job rather than a fault.
  • not-rendered — the renderer gates this service out on this install’s shape. The non-HA postgres and victoriametrics on an HA cluster install; on a single-node install those are the live ones and postgres-ha / vminsert / vmselect / vmstorage are gated out instead. Nothing can report it because nothing renders it.
string
Allowed values: expected data-plane not-rendered

Example 

{
  "items": [
    {
      "effective": {
        "memoryMax": "4g",
        "cpuQuota": "2.0",
        "memorySource": "node",
        "cpuSource": "node",
        "restart": "immediate"
      },
      "applicability": "expected"
    }
  ]
}

403

Section titled “403”

Authenticated but not authorized.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
>= 400 <= 599
detail
string
instance
string format: uri-reference
requestId
required
string
code
required
string
issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object
code
required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string
statement
required

Index of the statement at fault; -1 for the document as a whole.

integer
>= -1
detail
required
string
action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string
errors

Field errors, for codes that carry them: each problem at its field (see FieldError). Documented on the responses that set it, e.g. approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED. Absent otherwise.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object
field
required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string
message
required
string
details

Structured facts about the refusal, for codes that carry them. The shape is fixed per code and documented on the response that answers it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and IMAGE_IN_USE. Absent for codes that carry none.

object
key
additional properties
any

Example 

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}