Boost Kubernetes Scheduler Performance by Tuning percentageOfNodesToScore

The kube‑scheduler is the default scheduler in Kubernetes, responsible for assigning Pods to Nodes. A "schedulable" Node is one that can host a Pod, and the scheduler binds the chosen Node to the Pod via the kube‑apiserver.

This article explains ways to optimise scheduler performance in large clusters by configuring the percentageOfNodesToScore parameter, which balances scheduling latency and placement precision.

Setting the Threshold

The percentageOfNodesToScore option accepts integer values from 0 to 100. A value of 0 tells the scheduler to use its compiled default; values above 100 are treated as 100.

To change the setting, edit the scheduler configuration file (commonly /etc/kubernetes/config/kube-scheduler.yaml) and restart the scheduler.

After modification, verify the scheduler’s health with kubectl get componentstatuses, which should show the scheduler as Healthy.

Node Scoring Threshold

In large clusters, the scheduler can stop searching for additional schedulable Nodes once a sufficient number have been found, reducing the time spent on the filtering phase.

The threshold is expressed as a percentage of the total cluster nodes; the scheduler converts this to an integer count and stops once that many nodes are confirmed as schedulable.

Default Threshold

If the parameter is not set, Kubernetes computes a value using a linear formula: 50% for a 100‑node cluster, 10% for a 5,000‑node cluster, with a minimum of 5%.

Thus the scheduler will score at least 5% of the nodes unless the user sets a lower value. Setting the value to 100 forces scoring of every node.

Example

Below is an example configuration that sets percentageOfNodesToScore to 50%:

apiVersion: kubescheduler.config.k8s.io/v1alpha1
kind: KubeSchedulerConfiguration
algorithmSource:
  provider: DefaultProvider
...
percentageOfNodesToScore: 50

Adjusting the Parameter

The value must be between 1 and 100; the default is calculated from cluster size, and a hard‑coded minimum of 50 Nodes exists in the code.

Note: When the number of schedulable Nodes is fewer than 50, the scheduler will still examine all Nodes because the early‑stop condition cannot be satisfied. In small clusters, lowering the value has little effect, so the default should generally be kept.

Setting a very low value may cause many Nodes never to reach the scoring phase, potentially preventing high‑scoring Nodes from being considered. Typically the value is not set below 10, and only reduced when the scheduler’s throughput is critical and node scoring is less important.

How the Scheduler Iterates Over All Nodes

The scheduler traverses the Node list in a round‑robin manner to give every Node a fair chance. It starts at the head of the list, stops once the required percentage of Nodes is reached, and the next Pod’s scheduling resumes from the last stop position.

In multi‑zone clusters, Nodes are interleaved across zones. For example, with two zones:

Zone 1: Node 1, Node 2, Node 3, Node 4
Zone 2: Node 5, Node 6

The evaluation order will be:

Node 1, Node 5, Node 2, Node 6, Node 3, Node 4

After evaluating all Nodes, the scheduler wraps around to Node 1 and repeats the process.