Skip to content
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

add a doc for QueueingHint #43813

Merged
merged 4 commits into from
Nov 22, 2023
Merged

add a doc for QueueingHint #43813

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ba05f7a
add a doc for QueueingHint
sanposhiho Nov 4, 2023
0190eeb
fix based on reviews
sanposhiho Nov 4, 2023
5126f13
address the review
sanposhiho Nov 18, 2023
de6a641
fix based on review
sanposhiho Nov 21, 2023
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
37 changes: 31 additions & 6 deletions content/en/docs/concepts/scheduling-eviction/scheduling-framework.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,15 +43,18 @@ A scheduling or binding cycle can be aborted if the Pod is determined to
be unschedulable or if there is an internal error. The Pod will be returned to
the queue and retried.

## Extension points
## Interfaces

The following picture shows the scheduling context of a Pod and the extension
points that the scheduling framework exposes. In this picture "Filter" is
The following picture shows the scheduling context of a Pod and the interfaces
that the scheduling framework exposes. In this picture "Filter" is
equivalent to "Predicate" and "Scoring" is equivalent to "Priority function".
sanposhiho marked this conversation as resolved.
Show resolved Hide resolved

One plugin may register at multiple extension points to perform more complex or
One plugin may implement multiple interfaces to perform more complex or
stateful tasks.

Some interfaces are called as extension points which can be controled through
sanposhiho marked this conversation as resolved.
Show resolved Hide resolved
[Scheduler Configuration](/docs/reference/scheduling/config/#extension-points).

{{< figure src="/images/docs/scheduling-framework-extensions.png" title="Scheduling framework extension points" class="diagram-large">}}

### PreEnqueue {#pre-enqueue}
Expand All @@ -65,6 +68,28 @@ Otherwise, it's placed in the internal unschedulable Pods list, and doesn't get
For more details about how internal scheduler queues work, read
[Scheduling queue in kube-scheduler](https://github.com/kubernetes/community/blob/f03b6d5692bd979f07dd472e7b6836b2dad0fd9b/contributors/devel/sig-scheduling/scheduler_queues.md).

### EnqueueExtension

EnqueueExtension is the interface where the plugin can control
whether to retry scheduling of Pods rejected by this plugin, based on changes in the cluster.
Plugins that implement PreEnqueue, PreFilter, Filter, Reserve or Permit should implement this interface.

#### QueueingHint

{{< feature-state for_k8s_version="v1.28" state="beta" >}}

QueueingHint is a callback function for deciding whether a Pod can be requeued to the active queue or backoff queue.
It's executed every time a certain kind of events happen,
and when the QueueingHint finds that the event might make the Pod schedulable,
sanposhiho marked this conversation as resolved.
Show resolved Hide resolved
the Pod is put into the active queue or the backoff queue
so that the scheduler will retry the scheduling of the Pod.

{{< note >}}
QueueingHint is a beta-level field and is enabled by default in 1.28.
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
QueueingHint is a beta-level field and is enabled by default in 1.28.
QueueingHint is a beta-level feature and is enabled by default in 1.28.

(it's not an API field)

Copy link
Contributor

Choose a reason for hiding this comment

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

This isn't quite right either. Try something like “Queuing hint evaluation during scheduling is a beta-level feature…”, or “the QueueingHint scheduler frobnication is a beta feature…” (change frobnication to a suitable term).

Copy link
Member Author

Choose a reason for hiding this comment

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

I go with:
QueueingHint evaluation during scheduling is a beta-level feature ..

You can disable it via the
`SchedulerQueueingHints` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/).
{{< /note >}}

### QueueSort {#queue-sort}

These plugins are used to sort Pods in the scheduling queue. A queue sort plugin
Expand Down Expand Up @@ -148,7 +173,7 @@ NormalizeScore extension point.

### Reserve {#reserve}

A plugin that implements the Reserve extension has two methods, namely `Reserve`
A plugin that implements the Reserve interface has two methods, namely `Reserve`
and `Unreserve`, that back two informational scheduling phases called Reserve
and Unreserve, respectively. Plugins which maintain runtime state (aka "stateful
plugins") should use these phases to be notified by the scheduler when resources
Expand Down Expand Up @@ -218,7 +243,7 @@ skipped**.

### PostBind {#post-bind}

This is an informational extension point. Post-bind plugins are called after a
This is an informational interface. Post-bind plugins are called after a
Pod is successfully bound. This is the end of a binding cycle, and can be used
to clean up associated resources.

Expand Down