From 5cd43e896be271631fde4c268492213324d2abae Mon Sep 17 00:00:00 2001 From: haser Date: Mon, 23 Oct 2023 22:54:06 +0800 Subject: [PATCH 1/4] [YUNIKORN-2035] Update queue api example in scheduler api document --- docs/api/scheduler.md | 210 ++++++++++++++++++++++++------------------ 1 file changed, 120 insertions(+), 90 deletions(-) diff --git a/docs/api/scheduler.md b/docs/api/scheduler.md index 494d2d3cc26..f28e31e3c49 100644 --- a/docs/api/scheduler.md +++ b/docs/api/scheduler.md @@ -160,99 +160,129 @@ 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. + +In the response, certain fields of the queue information will be omitted if their values are empty. + +| Field | Type | omitted if empty | Description | +|------------------------|-------------------|:-----------------|----------------------------------------------------------------------------------------------------------------------------| +| QueueName | string | false | Name of the queue. | +| Status | string | true | The status of the queue, could be `Draining`, `Active` or `Stopped`. | +| Partition | string | false | The name of the partition. | +| PendingResource | map[string]int64 | true | Collections of pending resources. | +| MaxResource | map[string]int64 | true | Collections of max resources. | +| GuaranteedResource | map[string]int64 | true | Collections of guaranteed resources. | +| AllocatedResource | map[string]int64 | true | Collections of allocated resources. | +| PreemptingResource | map[string]int64 | true | Collections of preempting resources. | +| IsLeaf | bool | false | True if the queue is a leaf queue. | +| IsManaged | bool | false | True if the queue is part of the config, not auto created. | +| Properties | map[string]string | true | A map from the property key to the value. | +| Parent | string | true | The parent of this queue. | +| TemplateInfo | *TemplateInfo | true | The child template of this queue. Define the behaviour of dynamic leaf queues. It will be named as `template` in response. | +| Children | []QueueInfo | true | Collections of the children. | +| AbsUsedCapacity | map[string]int64 | true | Collections of the absolute used resources as a percentage. | +| MaxRunningApps | uint64 | true | A number of the max running applications of this queue. | +| RunningApps | uint64 | true | A number of the current running applications of this queue. | +| CurrentPriority | int32 | true | A number of the priority, higher priority has higher value. | +| AllocatingAcceptedApps | []string | true | 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 From 148aeabf9524fbc26ca3cbf8c15b1fbd83624935 Mon Sep 17 00:00:00 2001 From: haser Date: Tue, 31 Oct 2023 18:23:32 +0800 Subject: [PATCH 2/4] change the go type to json type --- docs/api/scheduler.md | 50 +++++++++++++++++++++---------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/docs/api/scheduler.md b/docs/api/scheduler.md index 52c756680e0..50826f1435e 100644 --- a/docs/api/scheduler.md +++ b/docs/api/scheduler.md @@ -165,33 +165,33 @@ to the client. There are currently 2 applications, with 2 pods assigned to each application.
- Fields of the queue info -
+Fields of the queue info +
The response json is based on the queue info. -In the response, certain fields of the queue information will be omitted if their values are empty. - -| Field | Type | omitted if empty | Description | -|------------------------|-------------------|:-----------------|----------------------------------------------------------------------------------------------------------------------------| -| QueueName | string | false | Name of the queue. | -| Status | string | true | The status of the queue, could be `Draining`, `Active` or `Stopped`. | -| Partition | string | false | The name of the partition. | -| PendingResource | map[string]int64 | true | Collections of pending resources. | -| MaxResource | map[string]int64 | true | Collections of max resources. | -| GuaranteedResource | map[string]int64 | true | Collections of guaranteed resources. | -| AllocatedResource | map[string]int64 | true | Collections of allocated resources. | -| PreemptingResource | map[string]int64 | true | Collections of preempting resources. | -| IsLeaf | bool | false | True if the queue is a leaf queue. | -| IsManaged | bool | false | True if the queue is part of the config, not auto created. | -| Properties | map[string]string | true | A map from the property key to the value. | -| Parent | string | true | The parent of this queue. | -| TemplateInfo | *TemplateInfo | true | The child template of this queue. Define the behaviour of dynamic leaf queues. It will be named as `template` in response. | -| Children | []QueueInfo | true | Collections of the children. | -| AbsUsedCapacity | map[string]int64 | true | Collections of the absolute used resources as a percentage. | -| MaxRunningApps | uint64 | true | A number of the max running applications of this queue. | -| RunningApps | uint64 | true | A number of the current running applications of this queue. | -| CurrentPriority | int32 | true | A number of the priority, higher priority has higher value. | -| AllocatingAcceptedApps | []string | true | Collections of the allocating accepted applications name. | +In the json response, certain fields of the queue information will be omitted if their values are empty. + +| Field | Type | omitted if empty | Description | +|------------------------|----------|:-----------------|----------------------------------------------------------------------------------------------------------------------------| +| QueueName | string | false | Name of the queue. | +| Status | string | true | The status of the queue, could be `Draining`, `Active` or `Stopped`. | +| Partition | string | false | The name of the partition. | +| PendingResource | object | true | Collections of pending resources. | +| MaxResource | object | true | Collections of max resources. | +| GuaranteedResource | object | true | Collections of guaranteed resources. | +| AllocatedResource | object | true | Collections of allocated resources. | +| PreemptingResource | object | true | Collections of preempting resources. | +| IsLeaf | boolean | false | True if the queue is a leaf queue. | +| IsManaged | boolean | false | True if the queue is part of the config, not auto created. | +| Properties | object | true | A map from the property key to the value. | +| Parent | string | true | The parent of this queue. | +| TemplateInfo | object | true | The child template of this queue. Define the behaviour of dynamic leaf queues. It will be named as `template` in response. | +| Children | object[] | true | Collections of the children. | +| AbsUsedCapacity | object | true | Collections of the absolute used resources as a percentage. | +| MaxRunningApps | number | true | A number of the max running applications of this queue. | +| RunningApps | number | true | A number of the current running applications of this queue. | +| CurrentPriority | number | true | A number of the priority, higher priority has higher value. | +| AllocatingAcceptedApps | string[] | true | Collections of the allocating accepted applications name. |
From efc6eccfeb04d765c1a2456b29a5f55c40cb37f3 Mon Sep 17 00:00:00 2001 From: haser Date: Wed, 1 Nov 2023 22:37:33 +0800 Subject: [PATCH 3/4] remove the 'omitted if empty' column --- docs/api/scheduler.md | 47 ++++++++++++++++++++++--------------------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/docs/api/scheduler.md b/docs/api/scheduler.md index 50826f1435e..fba7304fab5 100644 --- a/docs/api/scheduler.md +++ b/docs/api/scheduler.md @@ -31,6 +31,9 @@ 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. +Additionally, it should be note that 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 @@ -169,29 +172,27 @@ There are currently 2 applications, with 2 pods assigned to each application.
The response json is based on the queue info. -In the json response, certain fields of the queue information will be omitted if their values are empty. - -| Field | Type | omitted if empty | Description | -|------------------------|----------|:-----------------|----------------------------------------------------------------------------------------------------------------------------| -| QueueName | string | false | Name of the queue. | -| Status | string | true | The status of the queue, could be `Draining`, `Active` or `Stopped`. | -| Partition | string | false | The name of the partition. | -| PendingResource | object | true | Collections of pending resources. | -| MaxResource | object | true | Collections of max resources. | -| GuaranteedResource | object | true | Collections of guaranteed resources. | -| AllocatedResource | object | true | Collections of allocated resources. | -| PreemptingResource | object | true | Collections of preempting resources. | -| IsLeaf | boolean | false | True if the queue is a leaf queue. | -| IsManaged | boolean | false | True if the queue is part of the config, not auto created. | -| Properties | object | true | A map from the property key to the value. | -| Parent | string | true | The parent of this queue. | -| TemplateInfo | object | true | The child template of this queue. Define the behaviour of dynamic leaf queues. It will be named as `template` in response. | -| Children | object[] | true | Collections of the children. | -| AbsUsedCapacity | object | true | Collections of the absolute used resources as a percentage. | -| MaxRunningApps | number | true | A number of the max running applications of this queue. | -| RunningApps | number | true | A number of the current running applications of this queue. | -| CurrentPriority | number | true | A number of the priority, higher priority has higher value. | -| AllocatingAcceptedApps | string[] | true | Collections of the allocating accepted applications name. | +| 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. |
From 2a1c2015933158eedc1d8bba1e8ec6e689a655ea Mon Sep 17 00:00:00 2001 From: haser Date: Thu, 30 Nov 2023 22:44:06 +0800 Subject: [PATCH 4/4] use the note label in the overview. --- docs/api/scheduler.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/api/scheduler.md b/docs/api/scheduler.md index fba7304fab5..9bbbae8eba6 100644 --- a/docs/api/scheduler.md +++ b/docs/api/scheduler.md @@ -31,7 +31,8 @@ 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. -Additionally, it should be note that 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. +:::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`.