Skip to content
StratumStratum Docs

How many more of each instance type the cluster can place.

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

. For every active instance type: how many more fit on each VM-capable node, summed per availability zone and in total, and which dimension (vCPU, memory, a countable capability) runs out first.

Derived on read from the node rows and the catalog, with the same arithmetic the scheduler’s filter and the reservation use: capacity is (total - reserved) x overcommit ratio for vCPU and memory alike, and only ready nodes count. No capacity is reserved, so the answer is advisory in the same way the evacuation plan is. With no storage class a launch has nowhere for its root volume, so every type fits 0 and storage binds.

notModeled names the dimensions the answer does not account for. A number that covers two dimensions reads as authoritative on all of them unless the response says otherwise.

Gated by compute:ListNodes, like the node list it is derived from.

Authorizations

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”

The capacity report.

Media typeapplication/json

Headroom per instance type.

object
generatedAt
required
string format: date-time
items
required
Array<object>

One instance type’s headroom across the cluster.

object
instanceType
required
string
vcpus
required
integer
memoryBytes
required
integer format: int64
architecture
required
string
fits
required

How many more could be placed, summed over nodes. Exact for one type, since an instance never spans nodes.

integer
binding

The dimension that bounds the most eligible nodes: vcpu, memory, capability:<key>, or storage when the cluster has no storage class (every launch is then refused with 409 NO_STORAGE_CLASS, so fits is 0,). Absent when no node is eligible.

string
bindingNodes
required

How many eligible nodes each dimension bounds.

object
key
additional properties
integer
byAvailabilityZone
required

Per-AZ sums. The scheduler places within one AZ, so this is what one launch can use.

Array<object>
object
availabilityZone
required
string
fits
required
integer
nodes
required
Array<object>
object
nodeId
required
string
nodeName
required

The node’s name, the one the node list shows (not its hostname).

string
availabilityZone
required
string
fits
required
integer
binding

The dimension that runs out first on this node; storage when the cluster has no storage class.

string
allocatableVCPUs

VCPUs the node can have committed, the same number the node view reports.

integer format: int64
allocatableMemoryBytes

Memory the node can have committed, the same number the node view reports.

integer format: int64
ineligible

Why the node takes none of this type regardless of room.

string
Allowed values: state role architecture labels taint cpu-model
notModeled
required

Dimensions the answer does not account for, each with why.

Array<object>
object
dimension
required
string
reason
required
string

Example 

{
  "items": [
    {
      "instanceType": "m1.large",
      "nodes": [
        {
          "ineligible": "state"
        }
      ]
    }
  ],
  "notModeled": [
    {
      "dimension": "network-bandwidth"
    }
  ]
}