Walk through how kube-scheduler decides which node an unscheduled pod lands on, naming the phases it goes through and what each one produces.

## The scheduler's job kube-scheduler is a control-plane component that watches the API server for **pods with an empty `spec.nodeName`**. For each one it picks a node and writes a `Binding`. It does not start containers — kubelet on the chosen node notices the pod is assigned to it and does that. Scheduling is therefore a *placement decision recorded in the API*, nothing more. Pods are pulled from a priority queue: an *active* queue ordered by pod priority (then by the time they became unschedulable), plus *backoff* and *unschedulable* queues that hold pods waiting to be retried when relevant cluster events occur. Pods are handled **one at a time** in the scheduling cycle, which is why the scheduler is a single-threaded decision maker with a concurrent tail. ## Phase 1 — Filter (predicates) The filter phase answers a yes/no question per node: *can this pod run here at all?* It is a hard, non-negotiable pass. Representative plugins: - **NodeResourcesFit** — do the pod's CPU/memory/ephemeral-storage/extended-resource **requests** fit in the node's allocatable minus the requests of pods already there? Note: *requests*, not actual usage. A node at 5% real CPU can still be "full". - **NodeUnschedulable** — skips nodes cordoned with `spec.unschedulable`. - **NodeName / NodeAffinity** — honours `spec.nodeName`, `nodeSelector`, and `requiredDuringSchedulingIgnoredDuringExecution` affinity. - **TaintToleration** — rejects nodes with `NoSchedule`/`NoExecute` taints the pod does not tolerate. - **NodePorts** — rejects nodes where a requested `hostPort` is already taken. - **VolumeBinding, VolumeRestrictions, node volume limits** — can the PVs be bound/attached here, and is the per-node attachment limit respected? - **PodTopologySpread, InterPodAffinity** — the *required* variants act as filters. The output is the **feasible node list**. If it is empty, the pod is unschedulable: `PostFilter` runs (preemption lives there), the pod goes back to the queue, and its event carries the aggregated reason — `0/40 nodes are available: 12 Insufficient cpu, 28 node(s) had untolerated taint {...}`. In large clusters the scheduler does not filter every node. `percentageOfNodesToScore` (default: adaptive, roughly 50% shrinking toward a 5% floor as the cluster grows) stops the sweep once *enough* feasible nodes are found, resuming from where it stopped last time so nodes are visited fairly. This trades a little placement quality for latency, and it means "the best node in the cluster" is not guaranteed — only the best among those examined. ## Phase 2 — Score (priorities) Every feasible node is scored 0–100 by each enabled score plugin; scores are normalised, multiplied by the plugin's **weight**, and summed. Common plugins: - **NodeResourcesFit** with a scoring strategy — `LeastAllocated` by default, which spreads pods toward emptier nodes; `MostAllocated` bin-packs; `RequestedToCapacityRatio` lets you shape the curve. - **NodeResourcesBalancedAllocation** — prefers nodes where CPU and memory utilisation end up balanced, avoiding a node with free memory but no CPU. - **ImageLocality** — favours nodes that already have the container image, cutting startup time. - **InterPodAffinity / NodeAffinity** — `preferredDuringScheduling…` terms contribute here rather than filtering. - **PodTopologySpread** — `ScheduleAnyway` constraints score here; it carries a higher default weight because spreading matters for availability. - **TaintToleration** — `PreferNoSchedule` taints reduce a node's score instead of excluding it. The highest total wins; equal totals are broken **randomly** (reservoir sampling), which is why identical pods do not all pile onto the same node. ## Reserve, Permit, and the binding cycle After picking a node the scheduler runs **Reserve** (plugins claim resources in their own caches, e.g. volume binding) and **Permit** (a plugin may approve, deny, or *wait* — this is how gang/co-scheduling extensions hold a pod until its peers are ready). It then **assumes** the pod is on that node in its internal cache so the next pod in the queue sees the capacity as taken, and hands off to the **binding cycle**, which runs **asynchronously** and in parallel with the next pod's scheduling cycle: `PreBind` (e.g. actually bind the PVC), `Bind` (write the Binding to the API), `PostBind`. That asynchrony is the source of a class of subtle behaviour. If binding fails — API error, a `PreBind` volume error — the scheduler runs **Unreserve**, drops the assumption and requeues the pod. And because the decision was made against a cached snapshot, the node's state can change in between; kubelet performs its own **admission check** when the pod arrives and may reject it with `OutOfcpu`/`OutOfmemory`, producing a failed pod on the node rather than a pending one. ## Extensibility All of the above is the **scheduling framework**: filter and score are just plugin extension points, configured by a `KubeSchedulerConfiguration` with named **profiles**. A pod selects a profile via `spec.schedulerName`, so one binary can serve several policies, and you can enable/disable plugins or change their weights per profile without forking the scheduler.