Kubernetes scheduler simulator

Write one node per line and one pod (or x3 replicas of it) per line, using Kubernetes quantities such as 500m CPU and 512Mi memory, or pick an example. Pods are scheduled in the order listed. Schedule next pod places one at a time: the table shows every node's filter result and scores for that pod, and the event list shows what kubectl describe pod would report.

kube-scheduler watches for pods that have no node, takes them from a queue one at a time, and for each one runs a scheduling cycle built from plugins. Filter plugins each check one rule and remove the nodes that break it; the nodes that remain are feasible. Score plugins then rate each feasible node from 0 to 100; each rating is multiplied by the plugin's weight and the results are added. The pod is bound to the node with the highest total. If no node is feasible, the pod stays Pending and the scheduler records a FailedScheduling event saying why.

In the default configuration of Kubernetes 1.36 the score weights are 3 for TaintToleration, 2 each for NodeAffinity, PodTopologySpread and InterPodAffinity, and 1 each for NodeResourcesFit, NodeResourcesBalancedAllocation and ImageLocality. The first four only differ between nodes when a pod or node states a preference (a PreferNoSchedule taint, a preferred affinity, a ScheduleAnyway spread constraint); the required versions of the same rules are filters.

Filters run in plugin order and a node is out at the first one that rejects it, so each node contributes one reason (NodeResourcesFit can name both CPU and memory). The FailedScheduling message counts the reasons and lists them in alphabetical order: in the Pending pod example, a pod requesting 3 CPUs and 6 GiB gets

0/4 nodes are available: 1 Insufficient cpu, 1 Insufficient memory, 1 node(s) had untolerated taint(s), 1 node(s) were unschedulable.

One node has too little CPU, one too little memory, one a GPU taint the pod does not tolerate, and one is cordoned. The real event continues with a preemption: part saying whether evicting lower-priority pods would help. The reasons map to fixes:

• Insufficient cpu / memory: lower the request, free capacity, or add nodes (the cluster autoscaler adds them when pods are Pending for this reason).
• untolerated taint(s): the node is reserved; add a toleration if the pod belongs there.
• didn't match Pod's node affinity/selector: no node has the labels the pod asks for.
• didn't match pod anti-affinity rules or topology spread constraints: the placement rules leave no room; add nodes in other zones or relax the rule.
• were unschedulable: the node is cordoned, usually for maintenance.

The NodeResourcesFit score has two built-in strategies. LeastAllocated, the default, scores each resource as (allocatable − requested) × 100 / allocatable, counting the new pod, and averages CPU and memory; empty nodes score highest, so pods spread out. MostAllocated scores requested × 100 / allocatable, so the fullest node that still fits wins and pods pack together. A 1 CPU, 2 GiB pod on an empty node with 4 CPUs and 16 GiB scores 81 with LeastAllocated and 18 with MostAllocated.

NodeResourcesBalancedAllocation prefers nodes where CPU and memory end up used in similar proportions, so that one resource is not exhausted while the other sits idle. It takes the standard deviation of the requested fractions (for two resources, half their difference), scores (1 − deviation) × 100 with and without the new pod, and since Kubernetes 1.36 rewards the change: 50 plus half of (50 + score with − score without). The pod above gets 71, for a total of 152.

In the Spread or pack example, LeastAllocated puts the six pods on 3 nodes (50%, 75%, 75% of CPU requested) and MostAllocated on 2 (100%, 100%, 0%), leaving a node empty. Spreading limits the damage when a node fails; packing leaves room for large pods and lets the cluster autoscaler remove idle nodes. The strategy is set in the scheduler configuration, not per pod.

Everything above uses the pods' resource requests, not what they actually consume. A node is full to the scheduler when the requests of its pods add up to its allocatable capacity, even if they are idle. This is what makes scheduling predictable, and it is why requests should be close to real needs: too high and nodes look full while idle, too low and pods are placed on nodes that cannot run them. For scoring, a container with no request is counted as 100 millicores of CPU and 200 MiB of memory.

Spreading has a cost of its own: fragmentation. In the Fragmentation example, six 1.25-CPU pods spread over three 4-CPU nodes leave 1.5 CPUs free on each, 4.5 in all, and a 2-CPU pod cannot fit anywhere: 0/3 nodes are available: 3 Insufficient cpu. With MostAllocated the same six pods fill two nodes and the large pod lands on node-3.

A taint on a node repels pods: with the NoSchedule effect, no new pod is placed there unless it has a matching toleration (NoExecute also evicts running pods that do not tolerate it). Taints keep ordinary workloads off special nodes such as GPU machines or the control plane. A toleration only permits a pod onto a tainted node; to make it go there, the pod also needs a nodeSelector or node affinity on the node's labels, which the NodeAffinity filter enforces.

Required pod anti-affinity keeps pods that match a label selector out of the same topology domain, such as the same node (kubernetes.io/hostname) or zone. It is all or nothing: with two nodes and three replicas that must not share a node, the third stays Pending with 0/2 nodes are available: 2 node(s) didn't match pod anti-affinity rules. The rule is checked both ways: a new pod is also kept off nodes where an existing pod's anti-affinity rejects it.

Topology spread constraints are the more flexible tool. With maxSkew: 1 over zones and whenUnsatisfiable: DoNotSchedule, a node is filtered out if placing the pod there would leave its zone more than one matching pod ahead of the zone with the fewest. In the Zone spread example the five web pods go node-1, node-3, node-4, node-2, node-3: the third goes to the small node in zone c even though larger nodes score higher, because zone c had none.

The simulator implements the default filters that depend on what you can describe here (NodeUnschedulable, TaintToleration, NodeAffinity through nodeSelector, NodeResourcesFit, PodTopologySpread with DoNotSchedule over zones, and required InterPodAffinity anti-affinity on the pod's own app label) and the two resource scores with kube-scheduler's integer arithmetic. It leaves out priorities and preemption, volumes, ports, pod-count limits, image locality and preferred rules, and it schedules pods strictly in the order given, where the real queue orders by priority and retries pending pods when the cluster changes.