diff --git a/docs/api/scheduler.md b/docs/api/scheduler.md index eb5c7b55617..9bbbae8eba6 100644 --- a/docs/api/scheduler.md +++ b/docs/api/scheduler.md @@ -31,6 +31,10 @@ Many of these APIs return collections of resources. Internally, all resources ar are returned in units of bytes while resources of type `vcore` are returned in units of millicores (thousands of a core). All other resource types have no specific unit assigned. +:::note In the JSON response bodies, some fields may be omitted if their values are empty. Specifically, if a field is not present in the response, it can be assumed that the value is empty/null. +::: + + Under the `allocations` field in the response content for the app/node-related calls in the following spec, `placeholderUsed` refers to whether or not the allocation is a replacement for a placeholder. If true, `requestTime` is the creation time of its placeholder allocation, otherwise it's that of the allocation's ask. `allocationTime` is the creation time of the allocation, and `allocationDelay` is simply the difference between `allocationTime` and `requestTime`. ## Partitions @@ -160,99 +164,127 @@ The queues' hierarchy is kept in the response json. **Content examples** -For the default queue hierarchy (only `root.default` leaf queue exists) a similar response to the following is sent back to the client: +For the default queue hierarchy (only `root.default` leaf queue exists) a similar response to the following is sent back +to the client. +There are currently 2 applications, with 2 pods assigned to each application. + +
+Fields of the queue info +
+The response json is based on the queue info. + +| Field | Type | Description | +|------------------------|----------|----------------------------------------------------------------------------------------------------------------------------| +| QueueName | string | Name of the queue. | +| Status | string | The status of the queue, could be `Draining`, `Active` or `Stopped`. | +| Partition | string | The name of the partition. | +| PendingResource | object | Collections of pending resources. | +| MaxResource | object | Collections of max resources. | +| GuaranteedResource | object | Collections of guaranteed resources. | +| AllocatedResource | object | Collections of allocated resources. | +| PreemptingResource | object | Collections of preempting resources. | +| IsLeaf | boolean | True if the queue is a leaf queue. | +| IsManaged | boolean | True if the queue is part of the config, not auto created. | +| Properties | object | A map from the property key to the value. | +| Parent | string | The parent of this queue. | +| TemplateInfo | object | The child template of this queue. Define the behaviour of dynamic leaf queues. It will be named as `template` in response. | +| Children | object[] | Collections of the children. | +| AbsUsedCapacity | object | Collections of the absolute used resources as a percentage. | +| MaxRunningApps | number | A number of the max running applications of this queue. | +| RunningApps | number | A number of the current running applications of this queue. | +| CurrentPriority | number | A number of the priority, higher priority has higher value. | +| AllocatingAcceptedApps | string[] | Collections of the allocating accepted applications name. | +
+
+ ```json -[ +{ + "queuename": "root", + "status": "Active", + "partition": "default", + "pendingResource": { + "memory": 0, + "pods": 0, + "vcore": 0 + }, + "maxResource": { + "ephemeral-storage": 1508763181056, + "hugepages-1Gi": 0, + "hugepages-2Mi": 0, + "memory": 100276580352, + "pods": 330, + "vcore": 24000 + }, + "allocatedResource": { + "memory": 800000000, + "pods": 4, + "vcore": 400 + }, + "isLeaf": false, + "isManaged": true, + "properties": { + "application.sort.policy": "stateaware" + }, + "template": { + "maxResource": { + "memory": 800000000, + "vcore": 80000 + }, + "guaranteedResource": { + "memory": 540000000, + "vcore": 8000 + }, + "properties": { + "application.sort.policy": "stateaware" + } + }, + "children": [ { - "queuename": "root", - "status": "Active", - "maxResource": { - "ephemeral-storage": 188176871424, - "hugepages-1Gi": 0, - "hugepages-2Mi": 0, - "memory": 8000000000, - "pods": 330, - "vcore": 8000 - }, - "guaranteedResource": { - "memory": 54000000, - "vcore": 80 - }, - "allocatedResource": { - "memory": 54000000, - "vcore": 80 - }, - "pendingResource": { - "memory": 54000000, - "vcore": 80 - }, - "isLeaf": "false", - "isManaged": "false", - "properties": { - "application.sort.policy": "stateaware" - }, - "parent": "", - "template": { - "maxResource": { - "memory": 8000000000, - "vcore": 8000 - }, - "guaranteedResource": { - "memory": 54000000, - "vcore": 80 - }, - "properties": { - "application.sort.policy": "stateaware" - } - }, - "partition": "default", - "children": [ - { - "queuename": "root.default", - "status": "Active", - "maxResource": { - "memory": 8000000000, - "vcore": 8000 - }, - "guaranteedResource": { - "memory": 54000000, - "vcore": 80 - }, - "allocatedResource": { - "memory": 54000000, - "vcore": 80 - }, - "pendingResource": { - "memory": 54000000, - "vcore": 80 - }, - "isLeaf": "true", - "isManaged": "false", - "properties": { - "application.sort.policy": "stateaware" - }, - "parent": "root", - "template": null, - "children": [], - "absUsedCapacity": { - "memory": 1, - "vcore": 0 - }, - "maxRunningApps": 12, - "runningApps": 4, - "allocatingAcceptedApps": [ - "app-1", - "app-2" - ] - } - ], - "absUsedCapacity": { - "memory": 1, - "vcore": 0 - } - } -] + "queuename": "root.default", + "status": "Active", + "partition": "", + "pendingResource": { + "memory": 0, + "pods": 0, + "vcore": 0 + }, + "maxResource": { + "memory": 800000000, + "vcore": 80000 + }, + "guaranteedResource": { + "memory": 540000000, + "vcore": 8000 + }, + "allocatedResource": { + "memory": 800000000, + "pods": 4, + "vcore": 400 + }, + "isLeaf": true, + "isManaged": true, + "properties": { + "application.sort.policy": "stateaware" + }, + "parent": "root", + "absUsedCapacity": { + "memory": 100, + "vcore": 0 + }, + "maxRunningApps": 12, + "runningApps": 2, + "currentPriority": -2147483648 + } + ], + "absUsedCapacity": { + "memory": 0, + "pods": 1, + "vcore": 1 + }, + "runningApps": 2, + "currentPriority": -2147483648 +} ``` ### Error response