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.

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 Scheduling Configuration reference doc #21437

Merged
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
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
Original file line number Diff line number Diff line change
Expand Up @@ -81,8 +81,8 @@ of the scheduler:

1. [Scheduling Policies](/docs/reference/scheduling/policies) allow you to
configure _Predicates_ for filtering and _Priorities_ for scoring.
1. [Scheduling Profiles](/docs/reference/scheduling/profiles) allow you to
configure Plugins that implement different scheduling stages, including:
1. [Scheduling Profiles](/docs/reference/scheduling/config/#profiles) allow you
to configure Plugins that implement different scheduling stages, including:
`QueueSort`, `Filter`, `Score`, `Bind`, `Reserve`, `Permit`, and others. You
can also configure the kube-scheduler to run different profiles.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -228,7 +228,7 @@ type PreFilterPlugin interface {

You can enable or disable plugins in the scheduler configuration. If you are using
Kubernetes v1.18 or later, most scheduling
[plugins](/docs/reference/scheduling/profiles/#scheduling-plugins) are in use and
[plugins](/docs/reference/scheduling/config/#scheduling-plugins) are in use and
enabled by default.

In addition to default plugins, you can also implement your own scheduling
Expand All @@ -237,5 +237,5 @@ plugins and get them configured along with default plugins. You can visit

If you are using Kubernetes v1.18 or later, you can configure a set of plugins as
a scheduler profile and then define multiple profiles to fit various kinds of workload.
Learn more at [multiple profiles](/docs/reference/scheduling/profiles/#multiple-profiles).
Learn more at [multiple profiles](/docs/reference/scheduling/config/#multiple-profiles).

Original file line number Diff line number Diff line change
Expand Up @@ -195,7 +195,7 @@ topology spread constraints are applied to a Pod if, and only if:
- It belongs to a service, replication controller, replica set or stateful set.

Default constraints can be set as part of the `PodTopologySpread` plugin args
in a [scheduling profile](/docs/reference/scheduling/profiles).
in a [scheduling profile](/docs/reference/scheduling/config/#profiles).
The constraints are specified with the same [API above](#api), except that
`labelSelector` must be empty. The selectors are calculated from the services,
replication controllers, replica sets or stateful sets that the Pod belongs to.
Expand All @@ -219,7 +219,7 @@ profiles:
{{< note >}}
The score produced by default scheduling constraints might conflict with the
score produced by the
[`DefaultPodTopologySpread` plugin](/docs/reference/scheduling/profiles/#scheduling-plugins).
[`DefaultPodTopologySpread` plugin](/docs/reference/scheduling/config/#scheduling-plugins).
It is recommended that you disable this plugin in the scheduling profile when
using default constraints for `PodTopologySpread`.
{{< /note >}}
Expand Down
2 changes: 1 addition & 1 deletion content/en/docs/reference/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ client libraries:
* [kube-proxy](/docs/reference/command-line-tools-reference/kube-proxy/) - Can do simple TCP/UDP stream forwarding or round-robin TCP/UDP forwarding across a set of back-ends.
* [kube-scheduler](/docs/reference/command-line-tools-reference/kube-scheduler/) - Scheduler that manages availability, performance, and capacity.
* [kube-scheduler Policies](/docs/reference/scheduling/policies)
* [kube-scheduler Profiles](/docs/reference/scheduling/profiles)
* [kube-scheduler Profiles](/docs/reference/scheduling/config#profiles)

## Design Docs

Expand Down
Original file line number Diff line number Diff line change
@@ -1,30 +1,57 @@
---
title: Scheduling Profiles
title: Scheduler Configuration
content_type: concept
weight: 20
---

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

The `KubeSchedulerConfiguration` is a configuration API for `kube-scheduler`
alculquicondor marked this conversation as resolved.
Show resolved Hide resolved
that can be provided as a file via `--config` command line flag.

<!-- overview -->

{{< feature-state for_k8s_version="v1.18" state="alpha" >}}
<!-- body -->

A scheduling Profile allows you to configure the different stages of scheduling
in the {{< glossary_tooltip text="kube-scheduler" term_id="kube-scheduler" >}}.
Each stage is exposed in a extension point. Plugins provide scheduling behaviors
by implementing one or more of these extension points.
## Minimal Configuration

You can specify scheduling profiles by running `kube-scheduler --config <filename>`,
using the component config APIs
([`v1alpha1`](https://pkg.go.dev/k8s.io/kube-scheduler@{{< param "fullversion" >}}/config/v1alpha1?tab=doc#KubeSchedulerConfiguration)
or [`v1alpha2`](https://pkg.go.dev/k8s.io/kube-scheduler@{{< param "fullversion" >}}/config/v1alpha2?tab=doc#KubeSchedulerConfiguration)).
The `v1alpha2` API allows you to configure kube-scheduler to run
[multiple profiles](#multiple-profiles).
A minimal configuration looks as follows:

```yaml
apiVersion: kubescheduler.config.k8s.io/v1beta1
kind: KubeSchedulerConfiguration
clientConnection:
kubeconfig: /etc/srv/kubernetes/kube-scheduler/kubeconfig
```

## Upgrading from `v1alpha2` to `v1beta1` {#beta-changes}
alculquicondor marked this conversation as resolved.
Show resolved Hide resolved

<!-- body -->
When migrating from `kubescheduler.config.k8s.io/v1alpha2` to `kubescheduler.config.k8s.io/v1beta1`,
beware of the following changes, if applicable:

- `.bindTimeoutSeconds` was moved as part of plugin args for `VolumeBinding`,
which can be configured separately per [profile](#profiles).
- `.extenders` are updated to satisfy API standards. In particular:
- `.extenders` decoding is case sensitive. All fields are affected.
- `.extenders[*].httpTimeout` is of type `metav1.Duration`.
- `.extenders[*].enableHttps` is renamed to `.extenders[*].enableHTTPS`.
- `RequestedToCapacityRatio` args decoding is case sensitive. All fields are affected.
- `DefaultPodTopologySpread` [plugin](#scheduling-plugins) is renamed to `SelectorSpread`.
- `Unreserve` extension point is removed from Profile definition. All `Reserve`
plugins implement an `Unreserve` call.

## Profiles

## Extension points
A scheduling Profile allows you to configure the different stages of scheduling
in the {{< glossary_tooltip text="kube-scheduler" term_id="kube-scheduler" >}}.
Each stage is exposed in a [extension point](#extension-points).
alculquicondor marked this conversation as resolved.
Show resolved Hide resolved
[Plugins](#scheduling-plugins) provide scheduling behaviors by implementing one
or more of these extension points.

A single instance of `kube-scheduler` can be configured to run
[multiple profiles](#multiple-profiles)
alculquicondor marked this conversation as resolved.
Show resolved Hide resolved

### Extension points

Scheduling happens in a series of stages that are exposed through the following
extension points:
Expand All @@ -43,23 +70,45 @@ extension points:
filtering phase. The scheduler will then select the node with the highest
weighted scores sum.
1. `Reserve`: This is an informational extension point that notifies plugins
when resources have being reserved for a given Pod.
when resources have been reserved for a given Pod. Plugins also implement an
`Unreserve` call that gets called in the case of failure during or after
`Reserve`.
1. `Permit`: These plugins can prevent or delay the binding of a Pod.
1. `PreBind`: These plugins perform any work required before a Pod is bound.
1. `Bind`: The plugins bind a Pod to a Node. Bind plugins are called in order
and once one has done the binding, the remaining plugins are skipped. At
least one bind plugin is required.
1. `PostBind`: This is an informational extension point that is called after
a Pod has been bound.
1. `UnReserve`: This is an informational extension point that is called if
a Pod is rejected after being reserved and put on hold by a `Permit` plugin.

alculquicondor marked this conversation as resolved.
Show resolved Hide resolved
For each extension point, you could disable specific [default plugins](#scheduling-plugins)
or enable your own. For example:

```yaml
apiVersion: kubescheduler.config.k8s.io/v1beta1
kind: KubeSchedulerConfiguration
profiles:
- plugins:
score:
disabled:
- name: NodeResourcesLeastAllocated
enabled:
- name: MyCustomPluginA
weight: 2
- name: MyCustomPluginB
weight: 1
```

You can use `*` as name in the disabled array to disable all default plugins
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
You can use `*` as name in the disabled array to disable all default plugins
You can use `*` as name in the disabled array to disable all default plugins

for that extension point. This can also be used to rearrange plugins order, if
desired.

## Scheduling plugins
### Scheduling plugins

The following plugins, enabled by default, implement one or more of these
extension points:

- `DefaultTopologySpread`: Favors spreading across nodes for Pods that belong to
- `SelectorSpread`: Favors spreading across nodes for Pods that belong to
{{< glossary_tooltip text="Services" term_id="service" >}},
{{< glossary_tooltip text="ReplicaSets" term_id="replica-set" >}} and
{{< glossary_tooltip text="StatefulSets" term_id="statefulset" >}}
Expand Down Expand Up @@ -99,7 +148,7 @@ extension points:
Extension points: `Score`.
- `VolumeBinding`: Checks if the node has or if it can bind the requested
{{< glossary_tooltip text="volumes" term_id="volume" >}}.
Extension points: `Filter`.
Extension points: `PreFilter`, `Filter`, `Reserve`, `PreBind`.
- `VolumeRestrictions`: Checks that volumes mounted in the node satisfy
restrictions that are specific to the volume provider.
Extension points: `Filter`.
Expand Down Expand Up @@ -147,10 +196,25 @@ that are not enabled by default:
Service across nodes.
Extension points: `PreFilter`, `Filter`, `Score`.

## Multiple profiles
### Multiple profiles

`kube-scheduler` can be configured to
alculquicondor marked this conversation as resolved.
Show resolved Hide resolved
run more than one profile. Each profile has an associated scheduler name. Each
profile can have a different set of plugins configured in its
[extension points](#extension-points).

```yaml
apiVersion: kubescheduler.config.k8s.io/v1beta1
kind: KubeSchedulerConfiguration
profiles:
- schedulerName: default-scheduler
- schedulerName: no-scoring-scheduler
plugins:
alculquicondor marked this conversation as resolved.
Show resolved Hide resolved
score:
disabled:
- name: '*'
```

Choose a reason for hiding this comment

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

Would it make sense to explain this example? For example by adding a paragraph:

The example above will configure kube-scheduler to run two schedulers: the default one and no-scoring-scheduler with the score extension point disabled for all plugins.

Copy link
Member Author

Choose a reason for hiding this comment

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

Good suggestion

Copy link
Contributor

Choose a reason for hiding this comment

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

this is interesting, so are we saying we will be able to use the same scheduler binary to act as two different schedulers based on the scheduler field in the Pod ?

Copy link
Member

Choose a reason for hiding this comment

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

Correct.


When using the component config API v1alpha2, a scheduler can be configured to
run more than one profile. Each profile has an associated scheduler name.
Pods that want to be scheduled according to a specific profile can include
the corresponding scheduler name in its `.spec.schedulerName`.

Expand All @@ -174,8 +238,6 @@ the same configuration parameters (if applicable). This is because the scheduler
only has one pending pods queue.
{{< /note >}}



## {{% heading "whatsnext" %}}

* Learn about [scheduling](/docs/concepts/scheduling-eviction/kube-scheduler/)
Expand Down
2 changes: 1 addition & 1 deletion content/en/docs/reference/scheduling/policies.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,5 +122,5 @@ The following *priorities* implement scoring:
## {{% heading "whatsnext" %}}

* Learn about [scheduling](/docs/concepts/scheduling-eviction/kube-scheduler/)
* Learn about [kube-scheduler profiles](/docs/reference/scheduling/profiles/)
* Learn about [kube-scheduler Configuration](/docs/reference/scheduling/config/)

1 change: 1 addition & 0 deletions static/_redirects
Original file line number Diff line number Diff line change
Expand Up @@ -184,6 +184,7 @@
/docs/reference/glossary/maintainer/ /docs/reference/glossary/approver/ 301

/docs/reference/kubectl/kubectl/kubectl_*.md /docs/reference/generated/kubectl/kubectl-commands#:splat 301
/docs/reference/scheduling/profiles/ /docs/reference/scheduling/config/#profiles 301
alculquicondor marked this conversation as resolved.
Show resolved Hide resolved

/docs/reporting-security-issues/ /security/ 301

Expand Down