Skip to content

docs: fix typo deserverd→deserved and add multi-tenant Queue example #500

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pushtisonawala wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: fix typo deserverd→deserved and add multi-tenant Queue example #500

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions docs/KeyFeatures/QueueResourceManagement.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,14 @@ sidebar_position: 5
* Supports multi-dimensional resource quota control (CPU, Memory, GPU, NPU, etc.)
* Provides three-level resource configuration mechanism:
* capability: Upper limit of queue resource usage
* deserverd: Deserved resource amount (when no other queues submit jobs, jobs in this queue can exceed the deserverd value; when multiple queues submit jobs and cluster resources are insufficient, resources exceeding the deserverd value can be reclaimed by other queues)
* deserved: Deserved resource amount (when no other queues submit jobs, jobs in this queue can exceed the deserved value; when multiple queues submit jobs and cluster resources are insufficient, resources exceeding the deserved value can be reclaimed by other queues)
* guarantee: Reserved resource amount (reserved resources can only be used by this queue, other queues cannot use them)

> Recommendations and Notes:
>
> 1. When configuring three-level resources, follow: guarantee ≤ deserverd ≤ capability;
> 2. guarantee/capability can be configured as needed, deserverd value must be configured when capacity plugin is enabled;
> 3. deserverd configuration recommendations: In peer queue scenarios, the sum of deserverd values of all queues equals the total cluster resources; In hierarchical queue scenarios, the sum of child queues' deserverd values equals the parent queue's deserverd value, but cannot exceed it.
> 1. When configuring three-level resources, follow: `guarantee <= deserved <= capability`;
> 2. guarantee/capability can be configured as needed, deserved value must be configured when capacity plugin is enabled;
> 3. deserved configuration recommendations: In peer queue scenarios, the sum of deserved values of all queues equals the total cluster resources; In hierarchical queue scenarios, the sum of child queues' deserved values equals the parent queue's deserved value, but cannot exceed it.
> 4. capability configuration notes: In hierarchical queue scenarios, child queue's capability value cannot exceed parent queue's capability value. If child queue's capability is not set, it will inherit parent queue's capability value.

* Supports dynamic resource quota adjustment
Expand Down Expand Up @@ -82,10 +82,10 @@ spec:

The capacity plugin enables quota control through precise resource configuration. Combined with [hierarchical queues](/docs/KeyFeatures/HierarchicalQueue), it can achieve more fine-grained multi-tenant resource allocation and facilitates big data workload migration to Kubernetes clusters.

> **Note**: When using cluster autoscaling components like Cluster Autoscaler or Karpenter, total cluster resources change dynamically. In this case, using capacity plugin requires manual adjustment of queue's deserverd values to adapt to resource changes.
> **Note**: When using cluster autoscaling components like Cluster Autoscaler or Karpenter, total cluster resources change dynamically. In this case, using capacity plugin requires manual adjustment of queue's deserved values to adapt to resource changes.

#### proportion plugin
Unlike the capacity plugin, the proportion plugin automatically calculates queue's deserved resource amount by configuring queue Weight values, without explicitly configuring deserverd values:
Unlike the capacity plugin, the proportion plugin automatically calculates queue's deserved resource amount by configuring queue Weight values, without explicitly configuring deserved values:

```yaml
apiVersion: scheduling.volcano.sh/v1beta1
Expand All @@ -99,16 +99,16 @@ spec:
memory: "40Gi"
```

When total cluster resource is `total_resource`, each queue's deserverd value is calculated as:
When total cluster resource is `total_resource`, each queue's deserved value is calculated as:
```
queue_deserved = (queue_weight / total_weight) * total_resource
```

Where `queue_weight` represents current queue's weight, `total_weight` represents sum of all queue weights, `total_resource` represents total cluster resources.

Compared to capacity plugin, capacity plugin allows direct configuration of queue's deserverd value, while proportion plugin automatically calculates queue's deserverd value through weight ratio. When cluster resources change (e.g., through Cluster Autoscaler or Karpenter scaling), proportion plugin automatically recalculates each queue's deserverd value based on weight ratios, requiring no manual intervention.
Compared to capacity plugin, capacity plugin allows direct configuration of queue's deserved value, while proportion plugin automatically calculates queue's deserved value through weight ratio. When cluster resources change (e.g., through Cluster Autoscaler or Karpenter scaling), proportion plugin automatically recalculates each queue's deserved value based on weight ratios, requiring no manual intervention.

> **Important Note**: The actual deserverd value is dynamically adjusted. If calculated `queue_deserved` is greater than total resource requests of PodGroups waiting to be scheduled in the queue, the final deserverd value will be set to the total request amount to avoid over-reservation of resources and improve overall utilization.
> **Important Note**: The actual deserved value is dynamically adjusted. If calculated `queue_deserved` is greater than total resource requests of PodGroups waiting to be scheduled in the queue, the final deserved value will be set to the total request amount to avoid over-reservation of resources and improve overall utilization.

> **Note**:
> 1. capacity plugin and proportion plugin must be used exclusively, they cannot be used simultaneously
Expand Down Expand Up @@ -236,4 +236,4 @@ This scenario works with both capacity plugin and proportion plugin:
>
> 2. The choice between plugins depends on whether you want to set deserved directly (capacity) or calculate deserved automatically through weights (proportion)
>
> 3. After Volcano v1.9.0, capacity plugin is recommended as it provides more intuitive resource configuration
> 3. After Volcano v1.9.0, capacity plugin is recommended as it provides more intuitive resource configuration
40 changes: 39 additions & 1 deletion versioned_docs/version-v1.10.0/Concepts/Queue.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,11 +89,49 @@ This field is used to configure [hierarchical queues](/docs/KeyFeatures/Hierarch
`Closing` indicates that the queue is becoming unavailable. It is a transient state. A `Closing` queue cannot accept any new PodGroups.
### Unknown
`Unknown` indicates that the queue status is unknown because of unexpected situations such as network jitter.

## Multi-tenant Example

In a multi-tenant cluster, each team can have their own Queue with separate resource limits. Here's an example with two teams:

```yaml
# Team A's queue - gets 4 CPUs guaranteed
apiVersion: scheduling.volcano.sh/v1beta1
kind: Queue
metadata:
name: team-a
spec:
capability:
cpu: "8"
memory: 16Gi
guarantee:
resource:
cpu: "4"
memory: 8Gi
reclaimable: true
---
# Team B's queue - gets 4 CPUs guaranteed
apiVersion: scheduling.volcano.sh/v1beta1
kind: Queue
metadata:
name: team-b
spec:
capability:
cpu: "8"
memory: 16Gi
guarantee:
resource:
cpu: "4"
memory: 8Gi
reclaimable: true
Comment on lines +98 to +126

@gemini-code-assist gemini-code-assist Bot May 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

The multi-tenant example uses the guarantee field to define resource limits, but the description at line 142 states that teams can share idle resources. According to the Volcano documentation (see line 57 of this file and line 30 of queue_resource_management.md), guarantee resources are strictly reserved and cannot be used by other queues even if idle.

To achieve the described sharing behavior, the deserved field should be used instead. The deserved field defines the fair-share amount that can be borrowed by other queues when not in use. Furthermore, deserved is a mandatory field when using the recommended capacity plugin (as noted in queue_resource_management.md line 35).

# Team A's queue - gets 4 CPUs deserved (shareable fair-share)
apiVersion: scheduling.volcano.sh/v1beta1
kind: Queue
metadata:
  name: team-a
spec:
  capability:
    cpu: "8"
    memory: 16Gi
  deserved:
    cpu: "4"
    memory: 8Gi
  reclaimable: true
---
# Team B's queue - gets 4 CPUs deserved (shareable fair-share)
apiVersion: scheduling.volcano.sh/v1beta1
kind: Queue
metadata:
  name: team-b
spec:
  capability:
    cpu: "8"
    memory: 16Gi
  deserved:
    cpu: "4"
    memory: 8Gi
  reclaimable: true

```

Each team submits their jobs to their own queue. If Team A's jobs are idle, Team B can use the extra resources, and vice versa.

@gemini-code-assist gemini-code-assist Bot May 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The explanation can be improved by using more precise terminology and correcting the grammatical consistency (using 'its' for the singular 'team').

Suggested change
Each team submits their jobs to their own queue. If Team A's jobs are idle, Team B can use the extra resources, and vice versa.
Each team submits its jobs to its own queue. If Team A's jobs are idle, Team B can use the extra resources (up to its capability), and vice versa.


## Note
#### default Queue
When Volcano starts, it automatically creates queue `default` whose `weight` is `1`. Subsequent jobs that are not assigned to a queue will be assigned to queue `default`.
#### root queue
When Volcano starts, it also creates a queue named root by default. This queue is used when the [hierarchical queue](/docs/KeyFeatures/HierarchicalQueue) feature is enabled, serving as the root queue for all queues, with the default queue being a child queue of the root queue.

> For more information on queue usage scenarios, please refer to [Queue Resource Management](/docs/KeyFeatures/QueueResourceManagement)
> For more information on queue usage scenarios, please refer to [Queue Resource Management](/docs/KeyFeatures/QueueResourceManagement)