Proposal: feat(capacity) parent-based reclaim

[hajnalmt]

What type of PR is this?

/kind feature
/area scheduling

What this PR does / why we need it:

This PR adds parent-based reclaim configuration in the capacity plugin and keeps reclaim victim selection aligned with scheduler ordering semantics in hierarchical queue scenarios.

From design perspective only one shall be merged from:

• Proposal: feat(capacity) parent-based reclaim #5111
• Proposal: feat(capacity) ancestor-based reclaim with level #5115

It carries prerequisite victim-selection foundation commits so related scheduler tests pass reliably on this branch.

It also updates ReclaimableFn victim processing to use BuildVictimsPriorityQueue, aligning reclaim victim selection with scheduler victim-ordering semantics.

Which issue(s) this PR fixes:

Fixes #5107

Special notes for your reviewer:

• Prerequisite victim-selection commits (from enhancement(victim selection): improve same job-priority victim selection #5113) are required here for reliable test pass (reclaimee selection will be consistent with it):
  • 6200ee793 — enhancement(victim selection): add job ordering tie-break with task order
  • 9d98e3a21 — test(victim selection): add tie-break coverage in framework_test package
  • fdc34f9b3 — test(victim selection): strengthen tie-break proof and update docs
• Parent-based reclaim implementation commits follow those prerequisites.
• AI usage disclosure: I wrote this with my bare hands except the design doc change, that one is generated. BTW it's quite outdated anyway.

Does this PR introduce a user-facing change?

feat(capacity): added parent-based reclaim behavior in capacity plugin

[volcano-sh-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign shinytang6 for approval. For more information see the Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses issues with incorrect hierarchical reclaim behavior and unstable victim selection in parent-based reclaim scenarios. The changes ensure that victim selection consistently adheres to scheduler ordering semantics and respects parent-level resource deserving, thereby stabilizing reclaim decisions and preventing unintended preemption of borrowed capacity within a parent queue's quota.

Highlights

• Enhanced Victim Selection Ordering: Victim selection for capacity reclaim now consistently utilizes BuildVictimsPriorityQueue, ensuring that configured victim ordering is respected instead of relying on raw candidate iteration order.
• Improved Tie-Breaking in Victim Ordering: The victim queue ordering fallback mechanism has been improved to compare task order when job order is tied, stabilizing victim choice within the same queue during hierarchical reclaim.
• Parent-Based Reclaim Logic: Introduced parent-level deserved resource checks for cross-parent reclaim when parentBasedReclaimEnabled is active, preventing reclamation of borrowed capacity if the parent queue is still below its deserved quota.
• Updated Capacity Hierarchy Tests: Capacity hierarchy tests have been updated to enable priority ordering, ensure deterministic victim behavior, and remove test-local klog level overrides, validating the new reclaim semantics.
• Documentation Update: The hierarchical queue design document has been updated to clearly define the semantics of parentBasedReclaimEnabled and the gating logic for parent-level deserved resources.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• docs/design/hierarchical-queue-on-capacity-plugin.md
  • Added Story 5 to describe parent-based reclaim semantics and deserved gating.
  • Updated AddReclaimableFn description to include parent-level deserved checks for cross-parent reclaim.
• pkg/scheduler/framework/session_plugins.go
  • Added JobCompareFns to aggregate job ordering functions from plugins.
  • Modified BuildVictimsPriorityQueue to use JobCompareFns and TaskCompareFns for more robust victim ordering.
• pkg/scheduler/plugins/capacity/capacity.go
  • Defined parentBasedReclaimEnabled constant and added a corresponding field to capacityPlugin struct.
  • Initialized parentBasedReclaimEnabled from plugin arguments in the New function.
  • Added parentQueueID field to queueAttr struct.
  • Updated OnSessionOpen to log the status of parentBasedReclaimEnabled when hierarchy is enabled.
  • Changed victim iteration to use ssn.BuildVictimsPriorityQueue for ordered selection.
  • Implemented parent-level resource checks during victim selection when parentBasedReclaimEnabled is active.
  • Updated logging for reclaim eligibility checks to include parent queue details.
  • Populated parentQueueID in newQueueAttr.
• pkg/scheduler/plugins/capacity/capacity_test.go
  • Imported the priority plugin.
  • Added priority.New to the plugins map for hierarchical capacity tests.
  • Introduced new test resources (nodes, queues, podgroups, pods) to validate parent-based reclaim scenarios.
  • Added three new test cases (case13, case14, case15) to verify parent-based reclaim behavior, including scenarios with full clusters and non-preemptable queues.
  • Enabled priority plugin with EnabledJobOrder and EnabledTaskOrder in the default tier configuration for tests.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

The pull request introduces parent-based reclaim victim ordering in hierarchical capacity scheduling, addressing issue #5107. The changes involve updating documentation, modifying the session plugin to use a priority queue for victim selection, and implementing the core logic for parent-based reclaim in the capacity plugin. New test cases have been added to validate this functionality. However, a critical issue was identified in the reclaim logic where parent-level deserved checks are not consistently applied, potentially leading to incorrect reclaim decisions.

[Copilot]

Pull request overview

This PR fixes hierarchical capacity reclaim victim selection to respect configured victim ordering semantics (via BuildVictimsPriorityQueue) and adds parent-based deserved gating when parentBasedReclaimEnabled is enabled, along with corresponding tests and documentation updates.

Changes:

• Switch capacity reclaim victim iteration to consume candidates from BuildVictimsPriorityQueue to stabilize and correct victim ordering.
• Add optional parent-based deserved checks for cross-parent reclaim in hierarchical queues.
• Extend hierarchy tests to enable priority ordering and add parent-based reclaim scenarios; document the semantics in the design doc.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
pkg/scheduler/plugins/capacity/capacity_test.go	Enables priority ordering in tests and adds new parent-based reclaim test cases for deterministic victim selection.
pkg/scheduler/plugins/capacity/capacity.go	Implements queue parent tracking, parent-based reclaim gating, and uses the victims priority queue for reclaim ordering.
pkg/scheduler/framework/session_plugins.go	Adds job compare tie-breaker support and uses job/task compare functions to stabilize victim ordering.
docs/design/hierarchical-queue-on-capacity-plugin.md	Documents parentBasedReclaimEnabled semantics and parent-level deserved gating behavior in hierarchical reclaim.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.