Scheduler：Pod 的节点选择¶

Kubernetes 调度器是一个控制面进程，负责将 Pod 指派到节点上。调度器根据约束和可用资源，为调度队列中的每个 Pod 找出所有可以运行它的节点，再对这些节点排序，将 Pod 绑定到一个合适的节点。同一集群可以运行多个调度器；kube-scheduler 是 Kubernetes 的参考实现。

Scheduling Framework¶

Scheduling Framework 是 Kubernetes 调度器的可插拔架构。它由一组直接编译进调度器的插件 API 组成，使大多数调度功能可以通过插件实现，同时让调度核心保持轻量、易于维护。更多设计细节见 Scheduling Framework 设计提案。

整体架构¶

下图展示了 Pod 的调度上下文以及 Scheduling Framework 暴露的接口。一个插件可以实现多个接口，用于处理更复杂或需要保存状态的调度逻辑。部分接口对应可以通过调度器配置设置的扩展点。

图：Scheduling Framework 扩展点。来源：Kubernetes Scheduling Framework，CC BY 4.0。

一次 Pod 调度包含三个阶段：

• 进入调度队列：PreEnqueuePlugin 决定 Pod 能否进入活动队列，QueueSortPlugin 决定活动队列中的先后顺序。
• 调度阶段（Scheduling cycle）：Scheduler 串行处理 Pod，从队列中取出一个 Pod，过滤不符合条件的 Node，再对剩余 Node 评分，选出目标 Node。
• 绑定阶段（Binding cycle）：Scheduler 可以并发执行不同 Pod 的绑定阶段，完成卷绑定等准备工作，再将 Pod 绑定到选定的 Node，并通过 API Server 保存结果。

Kubernetes v1.36.4 的默认 Profile 通过 MultiPoint 启用插件，同一个插件会进入它所实现的所有扩展点。下表列出普通 Pod 调度路径中的扩展点、辅助接口及默认插件。

默认插件列表见 getDefaultPlugins，in-tree 插件构造函数注册在 NewInTreeRegistry。v1.36.4 默认启用 DynamicResourceAllocation 和 NodeDeclaredFeatures；Alpha 的 GangScheduling 与 TopologyAwareWorkloadScheduling 默认关闭，因此未列入普通 Pod 的默认路径。

Pod 调度过程¶

下面分别说明这三个阶段的处理过程。

进入调度队列

1. 观察 Pod：Scheduler 观察 API Server 中的 Pod 变化。已经设置 spec.nodeName 的 Pod 表示它已被分配到某个 Node，Scheduler 将它记录到本地 Scheduler Cache，用于计算 Node 的资源占用；尚未指定 Node 且由当前 Scheduler 负责的 Pod 进入 SchedulingQueue，等待调度。
2. 检查入队：PreEnqueue 检查 Pod 能否进入可调度队列。首次通过检查的 Pod 进入 activeQ；检查未通过时进入 unschedulablePods。
3. 等待重试：调度未能继续的 Pod 进入 unschedulablePods，等待可能改变结果的集群事件。Unschedulable 表示当前条件下无法完成调度；Pending 表示已经选出目标 Node，但插件需要等待外部组件根据调度结果完成操作，Pod 暂时不能进入绑定阶段。相关事件触发重新入队后，Pending Pod 直接进入 activeQ；Unschedulable Pod 在退避尚未结束时进入 podBackoffQ，退避结束后进入 activeQ。

调度阶段（Scheduling cycle）

1. 取出 Pod：Scheduler 从 SchedulingQueue 取出 Pod，读取当前的 Node 和资源状态。
2. 筛选 Node：PreFilter 准备筛选所需的状态，Filter 排除不满足硬约束的 Node。没有可行 Node 时，PostFilter 尝试抢占或其他补救措施；仍无法选出 Node 时，由 FailureHandler 记录失败原因，并将 Pod 交回 SchedulingQueue 等待重试。
3. 选择 Node：存在多个可行 Node 时，PreScore 准备评分所需的状态，Score 选择得分最高的 Node；只有一个可行 Node 时直接使用该 Node。
4. 记录选择：Scheduler 在本地 Cache 中记录目标 Node 和资源占用。Reserve 保存可回滚的临时状态，例如卷的预绑定信息；Permit 决定继续绑定、等待其他条件满足，或者拒绝本次选择。Reserve 或 Permit 失败时，Scheduler 先运行 Unreserve 撤销插件状态，再调用 ForgetPod 删除 Cache 中的 Assumed Pod。

绑定阶段（Binding cycle）

1. 检查 PreBind 插件：Scheduler 逐个运行 PreBindPreFlight，记录需要跳过的插件，以及哪些相邻插件可以在后续 PreBind 中并行执行。预检本身按顺序执行。
2. 等待 Permit 放行：Scheduler 调用 WaitOnPermit。只有 Permit 插件在调度阶段返回 Wait 时，这一步才会阻塞；否则立即进入 PreBind。等待期间保留目标 Node 的本地资源占用，插件拒绝或等待超时会撤销本次选择。
3. 准备绑定：PreBind 完成卷绑定等准备工作。
4. 提交绑定：Bind 负责提交绑定结果。默认 DefaultBinder 请求 Pod 的 binding 子资源，API Server 将目标 Node 写入 spec.nodeName。
5. 确认结果：PostBind 在绑定成功后运行。Scheduler 随后观察到已绑定的 Pod，并用新的 API 对象确认本地 Cache 中的 Assumed 状态。

进入调度队列¶

Pod 进入调度队列前，PreEnqueue 检查它是否已具备开始调度的条件。Pod 入队后，QueueSort 决定 activeQ 中的取出顺序；调度失败的 Pod 重新入队时，EnqueueExtensions 和 QueueingHint 决定哪些集群事件可以触发重试。

PreEnqueue¶

PreEnqueue 检查 Pod 是否已经具备开始调度的前置条件。例如，Pod 的 spec.schedulingGates 仍有条目时，内置 SchedulingGates 插件会阻止它进入可调度队列；控制器移除全部 gate 后，Pod 才会重新参加调度。

apiVersion: v1
kind: Pod
metadata:
  name: test-pod
spec:
  schedulingGates:
    - name: example.com/foo
    - name: example.com/bar
  containers:
    - name: pause
      image: registry.k8s.io/pause:3.6

SchedulingQueue 准备将 Pod 放入 activeQ 或 backoffQ 时，依次调用当前 Profile 中的 PreEnqueuePlugin.PreEnqueue。全部插件返回 Success 后，Pod 才会进入目标队列；任一插件返回失败状态时，调用立即停止，队列记录拒绝它的插件，并将 Pod 转入 unschedulablePods。这条分流可以在 moveToActiveQ 和 moveToBackoffQ 中看到。此后只有该插件关注的事件或通配事件才会触发重新检查。

QueueSort¶

activeQ 中可能同时存在多个 Pod，QueueSort 决定 Scheduler 下一次取出哪一个。

Pod C 和 Pod A 的 Priority 相同，入队更早的 Pod C 先被取出；Pod B 的 Priority 较低，最后取出。因此，取出顺序为 C、A、B。

QueueSortPlugin.Less 每次比较两个 QueuedPodInfo，activeQ 的堆结构使用比较结果维护上述顺序。newQueuedPodInfo 创建队列对象时将 Timestamp 设置为当前时间；一次调度失败后，AddUnschedulableIfNotPresent 在 Pod 重新入队前刷新该字段。InitialAttemptTimestamp 在 Pod 第一次进入 activeQ 时设置，之后保持不变，用于计算端到端调度延迟。

一个 Scheduler 进程中的所有 Profile 共享同一条调度队列，因此必须使用相同的 QueueSort 插件和配置。profile.Map 的校验逻辑会拒绝不一致的配置。

EnqueueExtensions¶

插件拒绝 Pod 后，SchedulingQueue 需要知道哪些集群变化可能改变上次的调度结果。EnqueueExtensions 让插件注册自己关注的事件，避免无关的 Node、Pod 或 PVC 变化反复触发调度。

Scheduler 启动时调用一次 EnqueueExtensions.EventsToRegister，并在运行期间沿用这份注册结果。该方法返回一组 ClusterEventWithHint：

• Event：指定插件关注的资源和动作，例如 Node label 更新。
• QueueingHintFn：接收上次调度失败的 Pod，以及事件涉及的新旧对象，判断这次变化是否值得让 Pod 重新入队。

例如，Pod 要求 Node 带有 storage=ssd label，但当前没有 Node 满足条件。Node label 更新后，NodeAffinity 的 QueueingHint 回调会重新检查该 Node：

• Node 从不匹配变为匹配时返回 Queue，Pod 可以重新入队。
• 更新后的 Node 仍不匹配时返回 QueueSkip，Pod 继续留在 unschedulablePods。

Queue 只说明这次事件可能改变调度结果，不保证 Pod 已经具备调度条件，也不直接决定它进入哪个队列。

收到 Queue 后，SchedulingQueue 再根据上次的插件状态选择入队方式：

• 返回 Queue 的插件此前将 Pod 标记为 Pending 时，Pod 跳过退避并进入 activeQ。
• 返回 Queue 的插件此前将 Pod 标记为 Unschedulable 时，Pod 根据剩余退避时间进入 podBackoffQ 或 activeQ。

Kubernetes v1.36.4 默认启用 SchedulerPopFromBackoffQ。Pod 从 unschedulablePods 写入 activeQ 或 podBackoffQ 前会重新运行 PreEnqueue；检查未通过时，Pod 继续留在 unschedulablePods。

PreEnqueue、PreFilter、Filter、Reserve 或 Permit 插件没有实现 EnqueueExtensions 时，Scheduler 会为它注册默认的全部已知集群事件。这样可以避免 Pod 因缺少事件注册而一直留在 unschedulablePods，代价是部分无关事件也会触发重新入队。EventsToRegister 返回错误时，Scheduler 无法启动。

调度阶段（scheduling cycle）¶

调度阶段为一个 Pod 选择目标 Node，并把选择结果写入 Scheduler 本地状态。CycleState 是本轮调度中插件共享计算结果的键值存储；每轮创建一份，轮次结束后不再复用。

PreFilter¶

多个 PreFilter 插件按照配置顺序串行执行，每个插件在当前 Pod 的调度周期中运行一次。插件接收当前 Pod 和全部候选 Node，可以把供后续 Filter 使用的计算结果写入 CycleState。PreFilterPlugin.PreFilter 还可以返回 PreFilterResult，把后续检查限制在一组 Node 中。

PreFilter 返回 Unschedulable 时，本轮不再检查 Node；返回 Skip 时，与它配套的 Filter 和 PreFilterExtensions 在本轮一起跳过。

CycleState 中的预计算结果反映了执行 PreFilter 时的 Node 状态。Scheduler 后续可能修改 NodeInfo 副本中的 Pod 集合，再使用修改后的状态运行 Filter。有些 PreFilter 结果取决于 Node 上已有的 Pod，例如 Pod 亲和性、拓扑分布和卷冲突的计数；如果只修改 NodeInfo，Filter 读取的 Node 状态和预计算结果就会不一致。

PreFilterExtensions 提供 AddPod 和 RemovePod 两个方法。Scheduler 在 NodeInfo 副本中加入 Pod 后调用 AddPod，移除 Pod 后调用 RemovePod，由相应的 PreFilter 插件同步更新 CycleState。

这两个方法主要用于以下两类调度计算：

• Nominated Pod 检查：对某个 Node 运行 Filter 前，Scheduler 会把已经提名该 Node、且优先级不低于当前 Pod 的 Pod 加入 NodeInfo 副本，并调用 AddPod。
• 抢占模拟：没有可行 Node 时，PostFilter 阶段的 DefaultPreemption 会修改 NodeInfo 副本并重新运行 Filter。它先移除可能被抢占的低优先级 Pod，并调用 RemovePod 更新预计算结果；当前 Pod 可以放入后，再逐个加回低优先级 Pod 并调用 AddPod，判断哪些 Pod 可以保留。这种增量更新避免了每次修改后重新执行完整的 PreFilter。DefaultPreemption 的模拟过程展示了这些调用。

这些操作只更新 Scheduler 的本地模拟状态，不会直接增删集群中的 Pod。

Filter¶

Filter 检查候选 Node 是否满足 Pod 的硬约束。FilterPlugin.Filter 每次接收 Pod 和一台候选 Node 的 NodeInfo；同一 Node 通过全部 Filter 插件后，才会进入可行节点集合。

常见 Filter 包括资源容量、Node affinity、taint、端口冲突和卷拓扑检查。插件的返回状态决定当前调度尝试如何继续：

• Success：当前插件接受该 Node，继续运行后续 Filter。
• Unschedulable：当前 Node 不满足条件，但条件可能通过集群状态变化或抢占得到解决。
• UnschedulableAndUnresolvable：当前 Node 的条件无法通过抢占解决，例如必需 label 不匹配。
• Error：插件执行失败，终止本次调度，并让 Pod 进入错误退避路径。

Filter 接口接收 NodeInfo。NodeInfo 聚合 Node 对象、已经分配和 Assumed 的 Pod、资源请求、端口、PVC 与镜像状态，插件使用传入的 NodeInfo 完成当前节点判断。

PostFilter¶

当 PreFilter 或 Filter 没有留下可行 Node 时，Scheduler 调用 PostFilter，尝试通过抢占等方式为当前 Pod 腾出资源。

默认的抢占插件会跳过 UnschedulableAndUnresolvable 的 Node，并检查移除哪些低优先级 Pod 后能够容纳当前 Pod。找到候选方案后，它发起抢占并返回 nominated Node。当前调度周期仍然结束，Pod 会在被抢占 Pod 退出后重新调度，不会从 PostFilter 直接进入绑定。

PostFilterPlugin.PostFilter 只在 PreFilter 或 Filter 返回不可调度结果时运行。没有插件能够改善结果时，Scheduler 记录 FailedScheduling Event，并将 Pod 放回不可调度队列或退避队列。

PreScore¶

通过 Filter 的 Node 多于一台时，PreScore 会先处理整组可行 Node，为后续评分准备共享状态。例如，拓扑相关插件可以先统计各拓扑域中的 Pod 数量，再由 Score 使用这些结果逐台打分。PreScorePlugin.PreScore 的计算结果保存在本轮 CycleState 中。

PreScore 返回 Skip 时，与它配套的 Score 插件在本轮一起跳过。Filter 只剩一台可行 Node 时，schedulePod 直接选择该 Node，不运行 PreScore 和 Score。

Score¶

Filter 留下多台可行 Node 时，Scheduler 运行 Score 插件为这些 Node 打分，再根据加权总分选择目标 Node。ScorePlugin.Score 每次接收 Pod 和一台 Node 的 NodeInfo，并返回该插件为这台 Node 计算的分数；分数越高，Node 越符合该插件的偏好。

NormalizeScore¶

Score 每次只为一台 Node 打分。某些插件得到的是原始值，需要看到全部候选 Node 后才能换算成可比较的分数。NormalizeScore 接收该插件产生的完整分数列表，并将每台 Node 的分数调整到 Framework 规定的 0–100 范围；分数越高，Node 越符合该插件的偏好。

假设一个插件按照 Node 上已经缓存的数据块数量打分，三台 Node 的原始值分别是 2、6 和 10，NormalizeScore 可以将它们映射为 0、50 和 100。

插件通过 ScoreExtensions() 提供可选的 NormalizeScore。返回 nil 表示 Score() 已经生成可以直接使用的分数，不需要再次归一化。Framework 校验最终分数是否位于 0–100，分数越界时本次调度失败。校验通过后，Framework 将每个插件的分数乘以 Profile 中配置的 weight，再把加权结果相加，选择总分最高的 Node。

Reserve¶

Scheduler 选出目标 Node 并在 Scheduler Cache 中 Assume Pod 后，Reserve 让插件把自己的临时状态同步到这次选择。它接收 Pod 和目标 Node 名称，不负责再次选择 Node。例如 VolumeBinding 会在本地缓存中 Assume 本轮选定的 PV 与 PVC 组合，避免其他调度周期同时使用这组卷绑定结果。

如果某个 Reserve 插件失败，或者后续 Permit、PreBind、Bind 失败，Framework 会按 Reserve 的相反顺序调用 Unreserve。VolumeBinding 会在这里撤销之前 Assume 的 PV 与 PVC 状态；Scheduler 随后还会 Forget Pod，释放 Scheduler Cache 中为目标 Node 记录的假定资源。

ReservePlugin 要求 Unreserve 保持幂等。Framework 可能在对应 Reserve 尚未运行时调用它，因此实现必须能够安全处理不存在的临时状态。

Permit¶

Permit 是进入绑定阶段前的最后一个决策点。它接收 Pod 和已经选定的 Node，在 Scheduler 完成 Assume 与 Reserve 后决定立即放行、保留当前结果继续等待，还是结束本次尝试。

例如，一组分布式训练 Pod 需要凑齐全部成员才能启动。Permit 插件可以让已经选到 Node 的成员返回 Wait；等全部成员都有位置后，插件再逐个调用 WaitingPod.Allow。等待期间，这些 Pod 仍占用 Scheduler Cache 中的 Assumed 资源，避免同一批资源被后续 Pod 选走。

PermitPlugin.Permit 可以返回以下结果：

• Success：当前插件接受这次选择，Framework 继续运行后面的 Permit 插件。全部插件执行完且没有等待、拒绝或错误时，Pod 进入绑定阶段。
• Wait：当前插件给出等待时长，Framework 继续运行后面的 Permit 插件。全部插件执行完且没有拒绝或错误时，只要存在一个 Wait，Scheduler 就会登记 WaitingPod；全部等待插件调用 Allow 后继续绑定，任一插件 Reject 或超时都会撤销本次选择。
• Pending：适用于外部组件需要根据本次节点选择完成后续操作、Pod 暂时还不能绑定的情况。例如，自定义 Permit 插件将目标 Node 交给外部设备分配控制器，等待它更新资源状态。插件返回 Pending 后，当前调度尝试结束。Scheduler 随后运行 Unreserve 和 ForgetPod，撤销本地预留；关联事件到达且 QueueingHint 返回 Queue 后，Pod 直接进入 activeQ，无需等待退避。
• Unschedulable：插件认为当前条件下无法继续调度，但抢占或集群状态变化可能解决问题。例如，移除低优先级 Pod 后，目标 Node 可能释放出足够的资源。Scheduler 撤销本地状态，并根据插件注册的事件等待重新调度。
• UnschedulableAndUnresolvable：插件确认抢占无法解决当前问题。例如，Pod 要求的 Node label 或卷拓扑与目标 Node 不匹配，移除其他 Pod 也不会改变结果。Scheduler 撤销本地状态，等待相关配置或对象发生变化后重新调度。
• Error：插件执行失败或收到意外输入。Scheduler 撤销本地状态，并按错误退避路径重试。

两者都会结束当前调度尝试并进入失败退避。区别在于 Unschedulable 表示 PostFilter 仍可能改善结果，而 UnschedulableAndUnresolvable 表示当前条件下无需尝试抢占。Permit 阶段已经选出目标 Node，两种状态使用相同的 Unreserve、ForgetPod 和重新入队流程。

每个 Permit 插件给出的 Wait 时长最多为 15 分钟；上限由 maxTimeout 定义。RunPermitPlugins 收集等待时长，Scheduler 登记 WaitingPod 时再由 newWaitingPod 为各插件启动计时器。任一计时器先到期，整个 Pod 的 Permit 等待都会失败。

绑定阶段（binding cycle）¶

绑定阶段把调度阶段选出的目标 Node 写入 Kubernetes API。在此之前，Scheduler 会等待 Permit 放行，并完成卷绑定等必须成功的准备工作；绑定成功后，再运行通知和清理类操作。

不同 Pod 可以并发执行绑定阶段。同一个 Pod 依次经过 PreBindPreFlight、WaitOnPermit、PreBind、Bind 和 PostBind。scheduleOnePod 为每个完成调度阶段的 Pod 启动一个 goroutine，并在其中调用 runBindingCycle。

WaitOnPermit¶

WaitOnPermit 确保所有请求等待的 Permit 插件都已放行，Pod 才能继续绑定。没有 Permit 插件返回 Wait 时，这一步立即成功；存在等待请求时，Scheduler 会等到所有相关插件调用 Allow、任一插件调用 Reject，或任一等待时限到期。

等待期间，Pod 仍以 Assumed 状态占用 Scheduler Cache 中的目标 Node 资源。等待失败后，Scheduler 运行 Unreserve 并从 Cache 中 ForgetPod，再由 FailureHandler 处理重新入队。

Framework.WaitOnPermit 先查询当前 Pod 的 WaitingPod 记录。没有记录时直接返回 nil，绑定流程继续执行 PreBind；存在记录时才会阻塞当前 Pod 的绑定 goroutine。它是 Framework 的内部步骤，不是插件扩展点。

PreBind¶

PreBind 在写入 Pod 与 Node 的绑定关系前，完成绑定所依赖的准备工作。例如，VolumeBinding 插件会把调度阶段确定的卷绑定结果提交给 API Server，并等待卷控制器完成绑定。

PreBind 插件接收 Pod、目标 Node 名称和本轮 CycleState。WaitOnPermit 成功后，所有需要运行的 PreBind 插件都必须返回 Success；任一插件失败都会终止本次绑定。

PreBindPlugin 同时包含 PreBindPreFlight 和 PreBind。PreBindPreFlight 只判断插件是否需要处理当前 Pod：Success 表示随后运行 PreBind，Skip 表示跳过，Error 表示终止绑定；AllowParallel 标记该插件的 PreBind 能否与相邻插件并行执行。

RunPreBindPreFlights 使用普通 for 循环逐个执行预检，并将 Skip 和 AllowParallel 结果写入 CycleState，预检本身不并行。RunPreBindPlugins 随后把连续允许并行的插件组成一组，并通过 Parallelizer().Until 并行执行组内插件；不允许并行的插件会截断分组并单独执行。

Bind¶

Bind 把已经选定的目标 Node 写入 Kubernetes API。绑定请求成功后，Pod 的 spec.nodeName 已经保存；Scheduler 的 Informer 随后收到 Pod 更新，并用它确认本地的 Assumed 状态。

BindPlugin.Bind 接收 Pod、目标 Node 名称和 CycleState，并按 Profile 中的配置顺序执行。Skip 表示当前插件不处理该 Pod，Framework 继续调用下一个插件；Success 表示绑定已经完成，其余 Bind 插件不再运行。所有插件都返回 Skip，或者任一插件失败时，本次绑定失败。

默认 DefaultBinder 构造一个 v1.Binding 请求体，并调用 Pod 的 binding 子资源。API Server 根据该请求更新现有 Pod 的 spec.nodeName；v1.Binding 在这里是请求对象，不是另行持久化的资源。具体调用见 DefaultBinder.Bind 和 API Server 的 BindingREST。

PostBind¶

PostBind 在 Bind 成功后执行，用于记录指标、发送通知或清理插件内部状态；这些操作不参与绑定是否成功的判断。

PostBind 插件接收 Pod、目标 Node 名称和 CycleState，并按配置顺序执行。PostBindPlugin.PostBind 没有返回状态，因此不能撤销已经完成的绑定；插件需要自行处理内部错误。

核心源码¶

下图展示 kube-scheduler 的核心组件与主要调用关系，涵盖初始化、插件管理、调度数据维护，以及 Pod 的调度、绑定和失败处理。

• Scheduler 结构：保存 SchedulingQueue、Cache、Profiles 和 nodeInfoSnapshot，并通过 NextPod、SchedulePod、FailureHandler 分别连接取出 Pod、选择 Node 和失败处理。
• Scheduler 初始化与启动：scheduler.New 创建 Framework、队列和 Cache，并注册事件处理函数。完成 Informer 数据同步且满足选主条件后，Scheduler.Run 启动队列后台任务和调度主循环。
• Scheduling Profile：将调度器名称、插件及其参数组合成一套调度策略。Pod 通过 spec.schedulerName 选择 Profile，Profiles 按该名称保存对应的 Framework。
• Framework 插件管理和调用：每个 Profile 对应一个 Framework，负责创建插件实例、维护各扩展点的插件列表，并通过 RunFilterPlugins、RunScorePlugins 等方法执行插件。
• Informer 与事件处理：通过 LIST/WATCH 接收 API Server 中的对象变化。事件处理函数将待调度 Pod 及相关事件送入 SchedulingQueue，将 Node 和已绑定 Pod 的变化写入 Cache。
• SchedulingQueue：管理待调度和等待重试的 Pod，使用 activeQ、backoffQ 和 unschedulablePods 保存不同状态的 Pod。NextPod 默认调用队列的 Pop，取出下一次调度要处理的 Pod。
• Scheduler Cache 与 Snapshot：Cache 汇总 Node、已绑定 Pod 和 Assumed Pod 的状态；每轮调度开始时，通过 UpdateSnapshot 刷新节点视图，供调度算法和插件读取。
• 调度阶段：ScheduleOne 取出 Pod 后调用 scheduleOnePod，由 schedulingCycle 同步完成节点选择和绑定前准备。选出 Node 后，先记录 Assumed 状态，再运行 Reserve 和 Permit。
• 绑定阶段：调度阶段成功后，scheduleOnePod 启动独立 goroutine 执行 runBindingCycle，完成等待 Permit、PreBind、Bind 和 PostBind。默认 Bind 插件向 API Server 提交 Pod 与 Node 的绑定请求。
• 失败处理：调度或绑定失败时，按需通过 Unreserve 和 ForgetPod 撤销插件状态与本地资源占用，再由 FailureHandler 记录诊断，并将仍需重试的 Pod 交回 SchedulingQueue。

Scheduler 结构¶

Scheduler 结构体集中保存调度器运行所需的本地数据和流程入口。SchedulingQueue、Cache、Profiles 和 nodeInfoSnapshot 提供调度数据；NextPod、SchedulePod 和 FailureHandler 分别连接取出 Pod、选择 Node 和失败处理流程。

• 保存本地数据：SchedulingQueue 保存待处理 Pod，Cache 汇总 Node 与 Pod 状态，Profiles 保存各调度策略对应的 Framework，nodeInfoSnapshot 提供本轮调度使用的节点视图。
• 取出 Pod：NextPod 默认指向 SchedulingQueue.Pop，队列为空时阻塞等待。
• 选择 Node：SchedulePod 默认指向 schedulePod，使用选定的 Framework 和 NodeInfo Snapshot 完成筛选与评分。
• 处理失败：FailureHandler 默认指向 handleSchedulingFailure，负责记录诊断信息并把 Pod 交回 SchedulingQueue。

下面的源码保留普通 Pod 调度主路径使用的字段。

type Scheduler struct {
    // 保存 Node、已绑定 Pod 和 Assumed Pod 的本地状态。
    Cache internalcache.Cache

    ...

    // 从调度队列中取出下一项；队列为空时阻塞等待。
    NextPod func(logger klog.Logger) (*framework.QueuedPodInfo, error)

    // 处理调度失败，记录诊断信息并把 Pod 交回队列。
    FailureHandler FailureHandlerFn

    // 执行节点筛选、评分和目标 Node 选择。
    SchedulePod func(
        ctx context.Context,
        fwk framework.Framework,
        state fwk.CycleState,
        podInfo *framework.QueuedPodInfo,
    ) (ScheduleResult, error)

    ...

    // 保存等待调度、退避和暂时不可调度的 Pod。
    SchedulingQueue internalqueue.SchedulingQueue

    // 按 schedulerName 保存各 Profile 对应的 Framework。
    Profiles profile.Map

    // 为当前调度周期提供稳定的 NodeInfo 视图。
    nodeInfoSnapshot *internalcache.Snapshot

    ...
}

Scheduler 初始化与启动¶

kube-scheduler 命令读取配置并创建 Scheduler，再启动 Informer、等待初始数据处理完成，最后进入 ScheduleOne 主循环。Leader Election 开启时，只有持有 Lease 的实例会运行主循环。

相关代码位置如下：

cmd/kube-scheduler/app/
├── server.go                       # 命令入口、Setup 与进程级 Run
└── config/config.go                # Config、CompletedConfig：保存进程运行配置

pkg/scheduler/
├── scheduler.go                    # New 创建组件，Run 启动队列与调度循环
├── eventhandlers.go                # 注册事件回调，等待初始对象处理完成
├── backend/queue/scheduling_queue.go # 队列 Run、退避刷新与停留超时检查
└── schedule_one.go                 # ScheduleOne：主循环调用的调度入口

下图展示了从命令入口到调度主循环的启动顺序。

命令与对象创建

• 创建命令：NewSchedulerCommand 创建 Cobra 命令，在 RunE 中调用 runCommand。runCommand 建立进程 Context，再调用 Setup。
• 创建 Scheduler：Setup 补齐配置默认值、校验配置，并收集 out-of-tree 插件，再调用 scheduler.New 创建 Scheduler。
• 启动进程服务：Setup 返回后，runCommand 调用 app.Run，启动事件广播、安全端口和健康检查，并按配置初始化 Informer、参与选主。

Informer 初始化与选主

• 初始化时机：

  • 未启用选主：直接初始化 Informer，完成后开始调度，DelayCacheUntilActive 的取值不影响这条路径。
  • 启用选主且 DelayCacheUntilActive = false：先初始化 Informer，再参与选主；成为 Leader 后开始调度。
  • 启用选主且 DelayCacheUntilActive = true：成为 Leader 后才初始化 Informer，完成后开始调度。

• Informer 初始化：app.Run 调用 InformerFactory.Start 启动 Informer，通过 WaitForCacheSync 等待初始缓存同步，再通过 WaitForHandlersSync 等待初始对象经过 Scheduler 注册的事件处理函数。

• 选主回调：启用选主时，实例成为 Leader 后执行 OnStartedLeading 回调。回调完成必要的 Informer 初始化后，调用 Scheduler.Run。

启动调度循环

• 启动队列后台任务：Scheduler.Run 先调用 SchedulingQueue.Run，分别在独立 goroutine 中运行两个任务：

  • 处理退避到期的 Pod：flushBackoffQCompleted 处理 podBackoffQ 和 podErrorBackoffQ 中退避已经结束的 Pod，将可以重新调度的 Pod 移入 activeQ，并唤醒等待取 Pod 的调度循环。
  • 检查长期未重试的 Pod：flushUnschedulablePodsLeftover 每隔 30 秒检查 unschedulablePods，对停留超过阈值的 Pod 触发重新入队检查。检查通过后，按剩余退避时间进入 activeQ 或 backoffQ；未通过则继续留在 unschedulablePods。

• 启动调度 goroutine：SchedulingQueue.Run 启动后台任务并返回后，Scheduler.Run 再创建独立 goroutine，串行循环调用 ScheduleOne，从队列取出 Pod 并执行调度。

• 等待停止信号：原 goroutine 阻塞在 <-ctx.Done()。Context 取消后，它关闭队列并清理插件；等待期间，队列后台任务和调度 goroutine 继续运行。

命令入口¶

NewSchedulerCommand 创建 Cobra 命令和配置选项，并在 RunE 中调用 runCommand。

runCommand 建立进程 Context 并调用 Setup；Setup 内部调用 scheduler.New，再把 CompletedConfig 和 Scheduler 返回给 runCommand。CompletedConfig 保存 Scheduler 进程运行所需的完整上下文，包括组件配置、API Client、Informer Factory、服务端和 Leader Election 配置。

func NewSchedulerCommand(registryOptions ...Option) *cobra.Command {
    opts := options.NewOptions()

    cmd := &cobra.Command{
        Use: "kube-scheduler",
        RunE: func(cmd *cobra.Command, args []string) error {
            // 命令参数解析完成后进入 Scheduler 的创建与运行流程。
            return runCommand(cmd, opts, registryOptions...)
        },
        ...
    }
    ...
    return cmd
}

func runCommand(
    cmd *cobra.Command,
    opts *options.Options,
    registryOptions ...Option,
) error {
    ...
    cc, sched, err := Setup(ctx, opts, registryOptions...)
    if err != nil {
        return err
    }
    // cc 保存进程运行配置和依赖，sched 是 scheduler.New 创建的调度器。
    // Run 使用二者启动 Informer、Leader Election 和调度主循环。
    return Run(ctx, cc, sched)
}

Setup 补齐配置默认值、校验配置并收集 out-of-tree 插件，再调用 scheduler.New 创建 Scheduler：

func Setup(
    ctx context.Context,
    opts *options.Options,
    outOfTreeRegistryOptions ...Option,
) (*config.CompletedConfig, *scheduler.Scheduler, error) {
    ...

    // 将 app.WithPlugin 注册的 out-of-tree 插件写入 Registry。
    outOfTreeRegistry := make(runtime.Registry)
    for _, option := range outOfTreeRegistryOptions {
        if err := option(outOfTreeRegistry); err != nil {
            return nil, nil, err
        }
    }

    // 传入配置、InformerFactory 和插件 Registry，创建 Scheduler。
    sched, err := scheduler.New(
        ctx,
        cc.Client,
        cc.InformerFactory,
        cc.DynInformerFactory,
        recorderFactory,
        scheduler.WithProfiles(cc.ComponentConfig.Profiles...),
        scheduler.WithFrameworkOutOfTreeRegistry(outOfTreeRegistry),
        ...,
    )
    ...
    return &cc, sched, nil
}

Scheduler 创建¶

scheduler.New 负责初始化 Scheduler。它合并 in-tree 插件 Registry 与 out-of-tree 插件 Registry，并完成以下初始化工作：

• Snapshot：保存本轮调度读取的节点视图，每轮调度开始时由 Scheduler Cache 增量刷新。
• Scheduler Cache：保存 Node、已绑定 Pod 和 Assumed Pod 的最新聚合状态。
• Scheduling Profile：profile.NewMap 为每个 Profile 创建 Framework，并按 schedulerName 写入 profile.Map。调度 Pod 时，Scheduler 根据 spec.schedulerName 取得对应的 Framework，运行该 Profile 配置的插件。
• SchedulingQueue：保存等待调度或等待重试的 Pod，所有 Profile 共用一个队列。
• 注册事件处理器：为 Pod、Node 和存储资源注册 Event Handler，用对象变化更新 SchedulingQueue 与 Scheduler Cache。

以下源码展示这些数据结构的创建、字段赋值和 Event Handler 注册位置：

func New(..., opts ...Option) (*Scheduler, error) {
    ...

    // 创建 Kubernetes 源码内置的 in-tree 插件 Registry。
    registry := frameworkplugins.NewInTreeRegistry()

    // 合并通过 app.WithPlugin 注册的 out-of-tree 插件。
    // 后续 Profile 根据插件名称从同一个 Registry 创建插件实例。
    if err := registry.Merge(options.frameworkOutOfTreeRegistry); err != nil {
        return nil, err
    }

    // Cache 持续接收 Informer 事件和 Assume、Forget 更新，保存最新的集群状态。
    // Snapshot 在每轮调度开始时由 Cache.UpdateSnapshot 增量刷新，供本轮调度读取。
    snapshot := internalcache.NewEmptySnapshot()
    schedulerCache := internalcache.New(
        ctx,
        apiDispatcher,
        feature.DefaultFeatureGate.Enabled(features.GenericWorkload),
    )

    // 每个 Profile 创建一个 Framework，并按 schedulerName 保存。
    profiles, err := profile.NewMap(
        ctx, options.profiles, registry, recorderFactory,
        frameworkruntime.WithSnapshotSharedLister(snapshot),
        ...,
    )
    if err != nil {
        return nil, fmt.Errorf("initializing profiles: %v", err)
    }

    // 所有 Profile 共用一个 SchedulingQueue。
    podQueue := internalqueue.NewSchedulingQueue(
        profiles[options.profiles[0].SchedulerName].QueueSortFunc(),
        informerFactory,
        ...,
    )

    sched := &Scheduler{
        // 保存持续变化的 Node 和 Pod 聚合状态。
        Cache:            schedulerCache,
        // 保存等待调度或等待重试的 Pod。
        SchedulingQueue:  podQueue,
        // 按 schedulerName 保存各 Profile 对应的 Framework，供调度 Pod 时查询。
        Profiles:         profiles,
        // 每轮调度开始时由 Cache.UpdateSnapshot 增量刷新。
        nodeInfoSnapshot: snapshot,
        ...,
    }
    // 主循环通过 NextPod 从 SchedulingQueue 取出下一个 Pod。
    sched.NextPod = podQueue.Pop
    // 设置默认的 SchedulePod 和 FailureHandler。
    sched.applyDefaultHandlers()

    // 从 SharedInformerFactory 取得 Pod、Node、PVC 等资源各自的 Shared Informer，
    // 并为它们注册 Add、Update 和 Delete 回调。
    // Informer 启动后，回调更新 SchedulingQueue 与 Scheduler Cache，并触发 Pod 重新入队。
    if err := addAllEventHandlers(sched, informerFactory, ...); err != nil {
        return nil, fmt.Errorf("adding event handlers: %w", err)
    }
    return sched, nil
}

数据同步与主循环¶

app.Run 是进程级运行入口，负责健康检查、事件广播、Shared Informer 同步和 Leader Election。WaitForCacheSync 等待各 Informer 完成第一次 LIST 并填充本地 Store，WaitForHandlersSync 等待这些对象经过 Scheduler 注册的 Event Handler。数据同步完成后调用 Scheduler.Run，启动 SchedulingQueue 后台任务和 ScheduleOne 主循环。

func Run(
    ctx context.Context,
    cc *schedulerserverconfig.CompletedConfig,
    sched *scheduler.Scheduler,
) error {
    logger := klog.FromContext(ctx)

    ...

    // 这里只定义启动 Informer 并等待同步的函数，尚未执行。
    // 后面根据 DelayCacheUntilActive 和 Leader Election 的状态调用它。
    startInformersAndWaitForSync := func(ctx context.Context) {
        // 启动 SharedInformerFactory 中已经创建的 Informer。
        cc.InformerFactory.Start(ctx.Done())
        if cc.DynInformerFactory != nil {
            cc.DynInformerFactory.Start(ctx.Done())
        }

        // 等待初始 LIST 完成，确保各 Informer 的 Store 已经填充。
        cc.InformerFactory.WaitForCacheSync(ctx.Done())
        if cc.DynInformerFactory != nil {
            cc.DynInformerFactory.WaitForCacheSync(ctx.Done())
        }

        // 等待初始对象经过 Scheduler 注册的 Event Handler。
        if err := sched.WaitForHandlersSync(ctx); err != nil {
            logger.Error(err, "handlers are not fully synchronized")
        }

        ...
    }

    // 未延迟缓存，或未启用 Leader Election 时，在这里调用并完成同步。
    if !cc.ComponentConfig.DelayCacheUntilActive || cc.LeaderElection == nil {
        startInformersAndWaitForSync(ctx)
    }

    if cc.LeaderElection != nil {
        ...

        cc.LeaderElection.Callbacks = leaderelection.LeaderCallbacks{
            OnStartedLeading: func(ctx context.Context) {
                ...

                // 延迟缓存时，当前实例成为 Leader 后才在这里调用该函数。
                if cc.ComponentConfig.DelayCacheUntilActive {
                    startInformersAndWaitForSync(ctx)
                }

                // 只有 Leader 进入 Scheduler 主循环。
                sched.Run(ctx)
            },
            OnStoppedLeading: func() {
                ...
            },
        }

        leaderElector, err := leaderelection.NewLeaderElector(*cc.LeaderElection)
        if err != nil {
            return fmt.Errorf("couldn't create leader elector: %v", err)
        }
        leaderElector.Run(ctx)
        return fmt.Errorf("lost lease")
    }

    // 未启用 Leader Election，当前实例直接运行 Scheduler。
    sched.Run(ctx)
    ...
}

delayCacheUntilActive 默认为 false，所有实例都会提前启动 Informer 并同步本地调度数据，以缩短 Leader 切换时间。设置为 true 后，备用实例成为 Leader 时才同步数据，可以减少内存和 API Server 开销，但会增加切换后的等待时间。当未启用 Leader Election 时，Informer 会立即启动。

Scheduler.Run 启动队列后台任务，并在独立 goroutine 中循环调用 ScheduleOne：

func (sched *Scheduler) Run(ctx context.Context) {
    // 启动退避刷新、不可调度 Pod 超时检查等队列任务。
    sched.SchedulingQueue.Run(klog.FromContext(ctx))

    ...

    // ScheduleOne 从 SchedulingQueue 取出下一个 Pod；队列为空时会阻塞等待。
    // 如果在当前 goroutine 中运行，Context 取消后将无法继续执行
    // SchedulingQueue.Close 来解除阻塞，导致关闭过程死锁，因此使用独立 goroutine。
    go wait.UntilWithContext(ctx, sched.ScheduleOne, 0)

    <-ctx.Done()
    sched.SchedulingQueue.Close()
    _ = sched.Profiles.Close()
}

Scheduling Profile¶

Scheduling Profile 将调度器名称、插件及其参数组合成一套调度策略。一个 kube-scheduler 进程可以配置多个 Profile，Pod 通过 spec.schedulerName 选择其中一套策略。kube-scheduler 随后按照该 Profile 的配置，在各个扩展点运行对应插件。

相关代码位置如下：

staging/src/k8s.io/kube-scheduler/config/v1/
└── types.go                        # KubeSchedulerProfile、插件列表与参数配置字段

pkg/scheduler/
├── apis/config/v1/
│   ├── defaults.go                 # 补齐 Profile 默认值与内置插件参数
│   └── default_plugins.go          # 默认插件集合，以及与用户插件配置的合并
├── profile/profile.go              # NewMap 创建并校验 Profile，保存 Framework
├── framework/runtime/framework.go  # NewFramework 按单份 Profile 创建插件运行环境
└── schedule_one.go                 # frameworkForPod 选择 Framework；计算可行节点数量

下图展示 Profile 的创建与选择：启动阶段将每份配置转换为 Framework，并以 schedulerName 为 key 写入 profile.Map；调度 Pod 时，Scheduler 根据 spec.schedulerName 取得对应的 Framework。

• 读取 Profile 配置：KubeSchedulerProfile 保存调度器名称、启用的插件及插件参数。
• 合并默认插件并补齐参数：Scheduler 将用户配置与内置插件集合合并，并补齐缺少的内置插件参数。
• 遍历 Profile：profile.NewMap 依次处理每份 Profile 配置。
• 创建 Framework：newProfile 为当前 Profile 调用 runtime.NewFramework。
• 校验 Profile：schedulerName 必须非空且唯一；多个 Profile 的 QueueSort 插件名称和参数必须一致。校验失败时，Scheduler 无法启动。
• 建立索引：校验通过后，Framework 以 schedulerName 为 key 写入 profile.Map。
• 读取调度器名称：调度 Pod 时，Scheduler 读取 spec.schedulerName。
• 查找 Framework：frameworkForPod 使用该名称查询 profile.Map；没有对应 Profile 时，本次调度返回错误。
• 运行插件：查询成功后，Scheduler 使用对应的 Framework 运行该 Profile 配置的插件。

Profile 配置¶

KubeSchedulerProfile 包含以下字段：

• schedulerName：Profile 的名称，与 Pod 的 spec.schedulerName 匹配。只有一个 Profile 且未填写名称时，默认值为 default-scheduler；配置多个 Profile 时，每个名称都必须非空且唯一。
• percentageOfNodesToScore：控制找到多少个可行 Node 后停止筛选。默认值 0 表示自动计算，公式为 max(5, 50 - Node 总数 / 125)%，同时至少查找 100 个可行 Node。例如，集群有 1,000 个 Node 时比例为 42%，找到 420 个可行 Node 后停止。numFeasibleNodesToFind 实现了这项计算。
• plugins：按扩展点启用、禁用或重新配置插件。enabled 可以添加插件，也可以覆盖默认插件在该扩展点上的顺序和 Score 权重；disabled 删除指定的默认插件，* 表示删除该扩展点的全部默认插件。
• pluginConfig：按插件名称提供初始化参数。一个插件实现多个扩展点时只创建一个实例，这组参数由该实例共同使用。

setDefaults_KubeSchedulerProfile 先把用户配置与默认插件集合合并。对于已经启用但没有配置参数的内置插件，Scheduler 会生成默认参数，供创建插件实例时使用。

func setDefaults_KubeSchedulerProfile(
    logger klog.Logger,
    prof *configv1.KubeSchedulerProfile,
) {
    // enabled、disabled 和 MultiPoint 配置在这里与默认插件合并。
    prof.Plugins = mergePlugins(logger, getDefaultPlugins(), prof.Plugins)

    scheme := GetPluginArgConversionScheme()
    existingConfigs := sets.New[string]()
    // 遍历用户显式提供的 pluginConfig，并为 Args 中未设置的字段补上默认值。
    for j := range prof.PluginConfig {
        // 记录已经配置过参数的插件，后续不再为它生成整份默认 pluginConfig。
        existingConfigs.Insert(prof.PluginConfig[j].Name)
        args := prof.PluginConfig[j].Args.Object
        // out-of-tree 插件参数由插件工厂自行解析并补齐默认值。
        if _, isUnknown := args.(*runtime.Unknown); isUnknown {
            continue
        }
        scheme.Default(args)
    }

    // 为其余内置插件补上对应的默认 Args。
    for _, name := range pluginsNames(prof.Plugins) {
        if existingConfigs.Has(name) {
            continue
        }
        ...
        prof.PluginConfig = append(prof.PluginConfig, configv1.PluginConfig{
            Name: name,
            Args: runtime.RawExtension{Object: args},
        })
    }
}

插件配置¶

这份配置包含两个 Profile。default-scheduler 使用默认插件；gpu-binpack-scheduler 调整插件权重、默认抢占和插件初始化参数。

gpu-binpack-scheduler 是本例定义的 Profile 名称。它继续使用 kube-scheduler 的内置插件，只通过 KubeSchedulerProfile 修改插件配置，不需要编写或编译新的调度插件。当内置插件无法满足调度规则时，可以使用 Scheduling Framework 编写自定义插件；后面的自定义调度插件通过完整示例介绍插件接口、注册、配置和验证过程。

apiVersion: kubescheduler.config.k8s.io/v1
kind: KubeSchedulerConfiguration
profiles:
  # 未配置插件时，Profile 使用 kube-scheduler 的默认插件和参数。
  - schedulerName: default-scheduler

  # 这个 Profile 倾向于集中放置 CPU、内存和 GPU 工作负载。
  - schedulerName: gpu-binpack-scheduler
    plugins:
      score:
        # 不再根据镜像是否已经缓存在 Node 上增加分数。
        disabled:
          - name: ImageLocality
        # 覆盖默认 Score 插件的权重；其他扩展点保持默认配置。
        enabled:
          - name: NodeResourcesFit
            weight: 5
          - name: PodTopologySpread
            weight: 3
      postFilter:
        # 没有可行 Node 时不运行默认抢占。
        disabled:
          - name: DefaultPreemption
    pluginConfig:
      - name: NodeResourcesFit
        args:
          # 优先选择资源利用率较高的 Node，集中放置工作负载。
          scoringStrategy:
            type: MostAllocated
            resources:
              - name: cpu
                weight: 1
              - name: memory
                weight: 1
              - name: nvidia.com/gpu
                weight: 5

• 多个 Score 插件：NodeResourcesFit 和 PodTopologySpread 仍在默认扩展点运行，这里只把它们的 Score 权重改为 5 和 3。
• 禁用单个插件：ImageLocality 只从 Score 扩展点移除；其他默认 Score 插件继续参与评分。
• 禁用默认抢占：DefaultPreemption 从 PostFilter 移除。该 Profile 找不到可行 Node 时，不会通过默认抢占移除低优先级 Pod。
• 配置插件参数：NodeResourcesFit 的 scoringStrategy.type 设置为 MostAllocated，资源已请求比例越高的 Node 得分越高。resources[].name 指定 CPU、内存和 GPU 参与评分，resources[].weight 将 nvidia.com/gpu 的比重设为 CPU 和内存的 5 倍。

Pod 设置 spec.schedulerName: gpu-binpack-scheduler 时，Scheduler 使用第二个 Profile；没有显式设置该字段的 Pod 由 API Server 默认填写 default-scheduler。

Profile 创建¶

profile.NewMap 为每份 Profile 创建 Framework，并以 schedulerName 建立索引；Framework 保存该 Profile 的插件实例和扩展点执行顺序，具体结构见 Framework 插件管理和调用。

profile.NewMap 遍历所有 Profile 配置。newProfile 将一份配置交给 frameworkruntime.NewFramework，创建对应的 Framework；校验通过后，再以 schedulerName 为 key 保存到 profile.Map：

func newProfile(
    ctx context.Context,
    cfg config.KubeSchedulerProfile,
    r frameworkruntime.Registry,
    recorderFact RecorderFactory,
    opts ...frameworkruntime.Option,
) (framework.Framework, error) {
    recorder := recorderFact(cfg.SchedulerName)
    opts = append(opts, frameworkruntime.WithEventRecorder(recorder))

    // 根据 Profile 的 plugins 和 pluginConfig 创建插件实例与执行链。
    return frameworkruntime.NewFramework(ctx, r, &cfg, opts...)
}

// Map 使用 schedulerName 索引各个 Profile 对应的 Framework。
type Map map[string]framework.Framework

func NewMap(...) (Map, error) {
    m := make(Map)
    v := cfgValidator{m: m}

    for _, cfg := range cfgs {
        // 每份 Profile 配置创建一个 Framework。
        p, err := newProfile(ctx, cfg, r, recorderFact, opts...)
        if err != nil {
            ...
        }

        // 检查 schedulerName 和多个 Profile 的 QueueSort 配置。
        if err := v.validate(cfg, p); err != nil {
            return nil, err
        }

        m[cfg.SchedulerName] = p
    }
    return m, nil
}

cfgValidator.validate 检查 Profile 名称是否为空或重复，并比较不同 Profile 的 QueueSort 插件及参数。

Profile 选择¶

调度一个 Pod 时，frameworkForPod 使用 spec.schedulerName 查询这个 Map：

func (sched *Scheduler) frameworkForPod(pod *v1.Pod) (framework.Framework, error) {
    // schedulerName 决定本次调度使用哪一组插件和插件参数。
    fwk, ok := sched.Profiles[pod.Spec.SchedulerName]
    if !ok {
        return nil, fmt.Errorf(
            "profile not found for scheduler name %q",
            pod.Spec.SchedulerName,
        )
    }
    return fwk, nil
}

选择同一个 Profile 的 Pod 复用同一个 Framework；每个 Pod 会创建独立的 CycleState，保存当前调度周期中的临时计算结果。

Framework 插件管理和调用¶

Framework 是 Scheduler 根据 Profile 创建的插件管理与调用对象。Scheduler 通过 Framework 运行当前 Profile 配置的扩展点插件。

相关代码位置如下，plugins/ 中列出部分内置插件实现：

pkg/scheduler/framework/
├── interface.go                    # Scheduler 内部使用的 Framework 接口
├── runtime/
│   ├── registry.go                 # Registry 与 PluginFactory：保存插件工厂
│   └── framework.go                # frameworkImpl、NewFramework 与扩展点插件调用
└── plugins/
    ├── registry.go                            # NewInTreeRegistry：注册内置插件工厂
    ├── schedulinggates/scheduling_gates.go     # SchedulingGates：PreEnqueue 检查调度门控
    ├── queuesort/priority_sort.go              # PrioritySort：按优先级和入队时间排序
    ├── nodeunschedulable/node_unschedulable.go # NodeUnschedulable：Filter 检查节点禁调度标记
    ├── nodeaffinity/node_affinity.go           # NodeAffinity：节点亲和性筛选与评分
    ├── noderesources/fit.go                    # NodeResourcesFit：资源请求检查与评分
    ├── defaultpreemption/default_preemption.go # DefaultPreemption：PostFilter 抢占，复用 Filter
    ├── volumebinding/volume_binding.go         # VolumeBinding：卷匹配与预留，在 PreBind 中绑定卷
    ├── defaultbinder/default_binder.go         # DefaultBinder：Bind 提交 Pod 绑定请求
    └── ...                                    # 其他内置插件未在此展开

staging/src/k8s.io/kube-scheduler/framework/
└── interface.go                    # 公开的 Handle、PluginsRunner 与扩展点插件接口

插件来源与配置

• 读取插件工厂：Registry 按插件名称保存 PluginFactory。NewFramework 根据 Profile 中启用的插件名称，从 Registry 取得对应工厂并创建插件实例。

• 读取插件列表：Profile 使用 plugins 指定各扩展点启用或禁用哪些插件，以及同一扩展点内的执行顺序。MultiPoint 可以把一个插件展开到它实现的多个扩展点。

• 读取插件参数：Profile 使用 pluginConfig 按插件名称提供初始化参数。同一个插件只读取一份参数，即使它同时实现 Filter、Score 等多个扩展点。

Framework 构建

• 创建 Framework：runtime.NewFramework 根据 Registry 和当前 Profile 创建 Framework，只初始化当前 Profile 实际启用的插件。

• 保存插件实例：frameworkImpl 是 Framework 的实现。每个插件名称在 pluginsMap 中只对应一个实例，多个扩展点可以引用同一个对象。

• 建立扩展点列表：frameworkImpl 按 Profile 配置建立 PreFilter、Filter、Score、Bind 等列表。列表保存插件实例和调用顺序，Run*Plugins 运行时直接读取对应列表。

• 保存 Score 权重：scorePluginWeight 按插件名称保存经过校验的 Score 权重。未设置或配置为 0 时使用 1，该权重只在 RunScorePlugins 汇总 Node 分数时使用。

接口分工

• 提供调度调用接口：Scheduler 通过 Framework 运行 PreEnqueue、PreFilter、PostFilter、Reserve、Permit、PreBind、Bind 和 PostBind 等插件。frameworkImpl 实现该接口，因此 Scheduler 不需要依赖具体插件类型。

• 提供插件共享能力：fwk.Handle 提供 Snapshot、Informer 和 ClientSet 等能力。Framework 嵌入 fwk.Handle；NewFramework 调用 PluginFactory 时，将当前 frameworkImpl 作为 Handle 参数传入，插件可以保存并使用它。

• 提供可复用运行方法：内部 Framework 嵌入 fwk.Handle，后者又嵌入 PluginsRunner，因此两者都包含 RunFilterPlugins、RunPreScorePlugins 和 RunScorePlugins 等方法。Scheduler 通过 Framework 调用，插件通过工厂传入的 Handle 调用；实际执行的都是当前 Profile 对应的 frameworkImpl 中的方法。

插件调用

• 调用扩展点插件：frameworkImpl 实现各扩展点的 Run*Plugins 方法。Scheduler 通过 Framework 接口调用这些方法；方法读取对应的扩展点列表，再按配置顺序调用插件实现。Filter 可以拒绝当前 Node，Permit 可以让 Pod 等待，Score 结果需要校验并乘以插件权重。

• Filter 调用示例：图中的 RunFilterPlugins 由 frameworkImpl 实现。它读取 filterPlugins，跳过本轮无需执行的插件，再按顺序调用各插件的 Filter() 方法；遇到首个非 Success 结果即返回。这里展示的是一台 Node 上的插件调用顺序，多台 Node 的检查由调度主流程并行发起。

• 实现插件逻辑：PluginFactory 创建具体插件实例，NewFramework 将实例保存到 pluginsMap。NodeResourcesFit、NodeAffinity 和 PodTopologySpread 等内置插件实现 PreScorePlugin、ScorePlugin 或其他扩展点接口，由 frameworkImpl 调用其 PreScore()、Score()、Filter() 等方法。同一个实例可以实现并加入多个扩展点列表。

Framework 接口¶

Framework 是 Scheduler 运行当前 Profile 插件的统一接口，由 frameworkImpl 实现。它嵌入 fwk.Handle，获得 NodeInfo Snapshot、Informer、Kubernetes Client 等共享能力，以及 PluginsRunner 定义的部分插件运行方法；Framework 本身再声明调度和绑定阶段需要的其他入口：

type Framework interface {
    // Handle 提供 Filter、PreScore、Score 和 SharedLister 等能力。
    fwk.Handle

    // 控制 Pod 入队条件、重试事件和 activeQ 的排序方式。
    PreEnqueuePlugins() []fwk.PreEnqueuePlugin
    EnqueueExtensions() []fwk.EnqueueExtensions
    QueueSortFunc() fwk.LessFunc

    // 运行筛选前的准备和无可行 Node 时的补救插件。
    RunPreFilterPlugins(
        ctx context.Context, state fwk.CycleState, pod *v1.Pod,
    ) (*fwk.PreFilterResult, *fwk.Status, sets.Set[string])
    RunPostFilterPlugins(
        ctx context.Context, state fwk.CycleState,
        pod *v1.Pod, filteredNodeStatusMap fwk.NodeToStatusReader,
    ) (*fwk.PostFilterResult, *fwk.Status)

    // 在写入 Binding 前后运行对应插件。
    RunPreBindPlugins(
        ctx context.Context, state fwk.CycleState, pod *v1.Pod, nodeName string,
    ) *fwk.Status
    RunPreBindPreFlights(
        ctx context.Context, state fwk.CycleState, pod *v1.Pod, nodeName string,
    ) *fwk.Status
    RunPostBindPlugins(
        ctx context.Context, state fwk.CycleState, pod *v1.Pod, nodeName string,
    )

    // Reserve 先占用插件内部资源；后续失败时按逆序运行 Unreserve。
    RunReservePluginsReserve(
        ctx context.Context, state fwk.CycleState, pod *v1.Pod, nodeName string,
    ) *fwk.Status
    RunReservePluginsUnreserve(
        ctx context.Context, state fwk.CycleState, pod *v1.Pod, nodeName string,
    )
    // Permit 可以放行、拒绝或让 Pod 等待外部条件。
    RunPermitPlugins(
        ctx context.Context, state fwk.CycleState, pod *v1.Pod, nodeName string,
    ) (pluginsWaitTime map[string]time.Duration, status *fwk.Status)
    AddWaitingPod(pod *v1.Pod, pluginsWaitTime map[string]time.Duration)
    WillWaitOnPermit(ctx context.Context, pod *v1.Pod) bool
    WaitOnPermit(ctx context.Context, pod *v1.Pod) *fwk.Status

    // Bind 插件提交 Pod 与 Node 的绑定关系。
    RunBindPlugins(
        ctx context.Context, state fwk.CycleState, pod *v1.Pod, nodeName string,
    ) *fwk.Status

    // ...
    Close() error
}

RunFilterPlugins、RunPreScorePlugins 和 RunScorePlugins 没有直接声明在上面的 Framework 接口中，而是定义在 PluginsRunner 中。Framework 嵌入 fwk.Handle，fwk.Handle 再嵌入 PluginsRunner，因此 Scheduler 仍然可以通过 Framework 调用这些方法：

type Handle interface {
    ...
    // 允许插件复用 Framework 的 Filter、PreScore 和 Score 执行逻辑。
    PluginsRunner
    ...
}

type PluginsRunner interface {
    RunPreScorePlugins(
        context.Context, CycleState, *v1.Pod, []NodeInfo,
    ) *Status
    RunScorePlugins(
        context.Context, CycleState, *v1.Pod, []NodeInfo,
    ) ([]NodePluginScores, *Status)
    RunFilterPlugins(
        context.Context, CycleState, *v1.Pod, NodeInfo,
    ) *Status
    ...
}

RunFilterPlugins、RunPreScorePlugins 和 RunScorePlugins 最初直接声明在 Framework 接口中，后来为了让获得 Handle 的插件复用这些运行方法，被提取到独立的 PluginsRunner 接口。例如，DefaultPreemption 实现了 PostFilterPlugin 接口，是 PostFilter 扩展点的默认抢占插件。它在结构体中保存 fwk.Handle；抢占模拟从 NodeInfo 副本中移除低优先级 Pod 后，SelectVictimsOnNode 通过 Handle 调用 RunFilterPluginsWithNominatedPods。该方法最终调用 RunFilterPlugins，复用当前 Profile 配置的 Filter 插件：

type DefaultPreemption struct {
    fh fwk.Handle
    ...
}

// 编译期确认 DefaultPreemption 实现 PostFilterPlugin 接口。
var _ fwk.PostFilterPlugin = &DefaultPreemption{}

func (pl *DefaultPreemption) SelectVictimsOnNode(
    ctx context.Context,
    state fwk.CycleState,
    pod *v1.Pod,
    nodeInfo fwk.NodeInfo,
    pdbs []*policy.PodDisruptionBudget,
) ([]*v1.Pod, int, *fwk.Status) {
    ...
    // 使用当前 Profile 的 Filter 插件检查移除候选 Pod 后的 Node。
    if status := pl.fh.RunFilterPluginsWithNominatedPods(
        ctx, state, pod, nodeInfo,
    ); !status.IsSuccess() {
        return nil, 0, status
    }
    ...
}

Framework 创建¶

Framework 创建时同时读取 Registry 和 Profile。Registry 保存插件名称与 PluginFactory 的对应关系；Profile 决定启用哪些插件，并通过 pluginConfig 提供初始化参数。PluginFactory 和 Registry 的定义如下：

// PluginFactory 使用插件配置和 Framework Handle 创建一个插件实例。
type PluginFactory = func(
    ctx context.Context,
    // configuration 对应当前插件的 pluginConfig.args。
    configuration runtime.Object,
    // f 向插件提供 Snapshot、Informer 和 ClientSet 等共享能力。
    f fwk.Handle,
) (fwk.Plugin, error)

// Registry 按插件名称保存对应的插件工厂。
type Registry map[string]PluginFactory

frameworkImpl 保存当前 Profile 启用的插件实例，并按扩展点组织执行列表。pluginsMap 按插件名称索引实例；一个插件即使实现多个扩展点，也只创建一个实例，各扩展点列表引用 pluginsMap 中的同一个对象。

每个列表的元素类型对应一个公开的扩展点接口。例如，filterPlugins []fwk.FilterPlugin 保存实现了 FilterPlugin 的插件实例，顺序来自 Profile 配置。RunFilterPlugins 遍历该列表时，循环变量 pl 表示其中一个插件实例，随后通过 pl.Filter(...) 调用它实现的 Filter 方法：

type frameworkImpl struct {
    registry Registry

    // 按插件名称保存经过校验的 Score 权重，仅 RunScorePlugins 使用。
    scorePluginWeight map[string]int

    // 各扩展点按 Profile 配置保存插件调用顺序。
    preEnqueuePlugins         []fwk.PreEnqueuePlugin
    enqueueExtensions         []fwk.EnqueueExtensions
    queueSortPlugins          []fwk.QueueSortPlugin
    preFilterPlugins          []fwk.PreFilterPlugin
    filterPlugins             []fwk.FilterPlugin
    postFilterPlugins         []fwk.PostFilterPlugin
    preScorePlugins           []fwk.PreScorePlugin
    scorePlugins              []fwk.ScorePlugin
    reservePlugins            []fwk.ReservePlugin
    preBindPlugins            []fwk.PreBindPlugin
    bindPlugins               []fwk.BindPlugin
    postBindPlugins           []fwk.PostBindPlugin
    permitPlugins             []fwk.PermitPlugin

    // 每个插件名称只对应一个实例，各扩展点列表引用这里的对象。
    pluginsMap map[string]fwk.Plugin

    ...
}

NewFramework 按以下顺序创建插件并建立扩展点列表：

1. 选择插件：读取当前 Profile 的 plugins 和 pluginConfig，再从 Registry 找到对应的插件工厂。

2. 创建插件实例：插件工厂收到配置参数和 Handle。Handle 是 Framework 提供给插件的共享能力接口，可以访问 NodeInfo Snapshot、Informer 和 Kubernetes Client 等能力。创建完成的实例按名称写入 pluginsMap。

3. 建立扩展点列表：updatePluginList 按 Profile 中的配置顺序，将 pluginsMap 中的实例加入 PreFilter、Filter、Score、Bind 等执行列表。同一个插件实现多个扩展点时，这些列表引用同一个实例。

4. 展开 MultiPoint：expandMultiPointPlugins 将 MultiPoint 中启用的插件加入它所实现的全部扩展点。某个扩展点存在显式的 enabled 或 disabled 配置时，以显式配置为准。

5. 保存 Score 权重：getValidScoreWeights 校验已启用 Score 插件的权重，并按插件名称写入 scorePluginWeight。权重没有设置或配置为 0 时使用 1。该权重只作用于 Score 扩展点。

func NewFramework(
    ctx context.Context,
    r Registry,
    profile *config.KubeSchedulerProfile,
    opts ...Option,
) (framework.Framework, error) {
    ...
    f := &frameworkImpl{
        registry: r,
        ...,
    }
    f.profileName = profile.SchedulerName

    // pg 只保留当前 Profile 启用的插件名称。
    pg := f.pluginsNeeded(profile.Plugins)
    pluginConfig := make(map[string]runtime.Object, len(profile.PluginConfig))
    for i := range profile.PluginConfig {
        name := profile.PluginConfig[i].Name
        if _, ok := pluginConfig[name]; ok {
            return nil, fmt.Errorf("repeated config for plugin %s", name)
        }
        pluginConfig[name] = profile.PluginConfig[i].Args
    }

    // pluginsMap 按名称保存当前 Profile 使用的唯一插件实例。
    f.pluginsMap = make(map[string]fwk.Plugin)
    for name, factory := range r {
        // Registry 包含全部已注册工厂，只创建当前 Profile 启用的插件。
        if !pg.Has(name) {
            continue
        }

        // PluginFactory 的第三个参数类型是 fwk.Handle。
        // f 是当前 frameworkImpl，向插件提供 Snapshot、Informer 和 ClientSet 等能力。
        args := pluginConfig[name]
        p, err := factory(ctx, args, f)
        if err != nil {
            return nil, fmt.Errorf("initializing plugin %q: %w", name, err)
        }
        // 扩展点列表随后通过插件名称复用这个实例。
        f.pluginsMap[name] = p
        // 收集插件关注的重新入队事件，未实现时使用默认事件集合。
        f.fillEnqueueExtensions(p)
    }

    // 将各扩展点显式启用的插件按配置顺序写入对应的执行列表。
    // updatePluginList 从 pluginsMap 取得实例，并检查它是否实现该扩展点接口。
    for _, point := range f.getExtensionPoints(profile.Plugins) {
        if err := updatePluginList(point.slicePtr, *point.plugins, f.pluginsMap); err != nil {
            return nil, err
        }
    }
    // MultiPoint 只需启用一次插件，再按插件实现的接口加入所有适用的扩展点。
    // 某个扩展点显式配置的 enabled 或 disabled 优先于 MultiPoint。
    if len(profile.Plugins.MultiPoint.Enabled) > 0 {
        if err := f.expandMultiPointPlugins(logger, profile); err != nil {
            return nil, err
        }
    }

    // 校验 Score 插件的权重；未设置或为 0 时按 1 处理。
    podScoreWeights, err := getValidScoreWeights(
        f,
        reflect.TypeFor[fwk.ScorePlugin](),
        append(profile.Plugins.Score.Enabled, profile.Plugins.MultiPoint.Enabled...),
    )
    if err != nil {
        return nil, fmt.Errorf("score plugins: %w", err)
    }
    // RunScorePlugins 按插件名称读取权重并计算加权分数。
    f.scorePluginWeight = podScoreWeights

    ...
    return f, nil
}

插件调用¶

Framework 按 Profile 配置的顺序调用同一扩展点的插件。以 RunFilterPlugins 为例：它逐个检查 Filter 插件，遇到第一个非 Success 结果便停止，并在返回状态中记录拒绝 Pod 的插件名。

func (f *frameworkImpl) RunFilterPlugins(
    ctx context.Context,
    state fwk.CycleState,
    pod *v1.Pod,
    nodeInfo fwk.NodeInfo,
) *fwk.Status {
    for _, pl := range f.filterPlugins {
        // PreFilter 返回 Skip 时，同名 Filter 插件在本轮一起跳过。
        if state.GetSkipFilterPlugins().Has(pl.Name()) {
            continue
        }

        if status := f.runFilterPlugin(ctx, pl, state, pod, nodeInfo); !status.IsSuccess() {
            // Filter 只应返回 Success 或拒绝状态；其他状态按插件错误处理。
            if !status.IsRejected() {
                status = fwk.AsStatus(fmt.Errorf(
                    "running %q filter plugin: %w", pl.Name(), status.AsError(),
                ))
            }
            // 失败状态携带插件名，供诊断和 QueueingHint 使用。
            status.SetPlugin(pl.Name())
            return status
        }
    }
    return nil
}

RunFilterPlugins 通过 runFilterPlugin 调用当前插件的 Filter 方法。CycleState 未要求记录插件指标时直接调用；需要记录时，runFilterPlugin 还会统计插件的执行时间和返回状态：

func (f *frameworkImpl) runFilterPlugin(
    ctx context.Context,
    pl fwk.FilterPlugin,
    state fwk.CycleState,
    pod *v1.Pod,
    nodeInfo fwk.NodeInfo,
) *fwk.Status {
    // 不记录当前插件的指标时，直接执行 Filter。
    if !state.ShouldRecordPluginMetrics() {
        return pl.Filter(ctx, state, pod, nodeInfo)
    }

    startTime := time.Now()
    status := pl.Filter(ctx, state, pod, nodeInfo)
    // 按扩展点、插件名和返回状态记录本次调用耗时。
    f.metricsRecorder.ObservePluginDurationAsync(
        metrics.Filter,
        pl.Name(),
        status.Code().String(),
        metrics.SinceInSeconds(startTime),
    )
    return status
}

pl 的类型是 fwk.FilterPlugin，实际调用的方法由当前插件实现。例如，内置 NodeUnschedulable.Filter 检查当前 Pod 能否放到被标记为不可调度的 Node：

func (pl *NodeUnschedulable) Filter(
    ctx context.Context,
    _ fwk.CycleState,
    pod *v1.Pod,
    nodeInfo fwk.NodeInfo,
) *fwk.Status {
    node := nodeInfo.Node()

    // Node 可以调度，返回 nil 表示检查通过。
    if !node.Spec.Unschedulable {
        return nil
    }

    logger := klog.FromContext(ctx)
    // Node 已被标记为不可调度，检查 Pod 是否容忍对应的 NoSchedule Taint。
    podToleratesUnschedulable := v1helper.TolerationsTolerateTaint(
        logger,
        pod.Spec.Tolerations,
        &v1.Taint{
            Key:    v1.TaintNodeUnschedulable,
            Effect: v1.TaintEffectNoSchedule,
        },
        utilfeature.DefaultFeatureGate.Enabled(
            features.TaintTolerationComparisonOperators,
        ),
    )
    if !podToleratesUnschedulable {
        // Pod 不容忍该 Taint，拒绝状态无法通过抢占等方式解决。
        return fwk.NewStatus(
            fwk.UnschedulableAndUnresolvable,
            ErrReasonUnschedulable,
        )
    }

    // Pod 容忍 node.kubernetes.io/unschedulable:NoSchedule，检查通过。
    return nil
}

SchedulingQueue¶

SchedulingQueue 是 Scheduler 使用的队列接口，定义等待调度 Pod 的加入、更新、取出和重新入队操作。

相关代码位置如下：

pkg/scheduler/
├── backend/queue/
│   ├── scheduling_queue.go         # SchedulingQueue、PriorityQueue 与重新入队策略
│   ├── active_queue.go             # activeQueue、取出 Pod 与调度期间的事件跟踪
│   ├── backoff_queue.go            # 普通退避与错误退避队列
│   └── unschedulable_pods.go        # 保存等待相关事件的不可调度 Pod
├── scheduler.go                    # 创建 SchedulingQueue 并启动后台任务
├── eventhandlers.go                # 将待调度 Pod 变化与相关集群事件交给队列
└── schedule_one.go                 # 取出 Pod，处理失败后的重新入队

下图展示 Pod 在 activeQ、backoffQ 和 unschedulablePods 之间的主要流转路径。

• 接收待调度 Pod：新增或更新、尚未指定 spec.nodeName 且由当前 Scheduler 负责的 Pod 被加入 SchedulingQueue。
• 检查首次入队：Pod 先运行 PreEnqueue。全部插件通过后进入 activeQ；任一插件拒绝后进入 unschedulablePods，并记录拒绝它的插件。
• 取出 Pod：Scheduler 按 QueueSort 的顺序从 activeQ 取出 Pod。启用 SchedulerPopFromBackoffQ 后，activeQ 为空时也可以直接从 podBackoffQ 取出一个 Pod。

• 执行调度与绑定：

  • 调度阶段成功：Scheduler 启动异步的绑定阶段。
  • 调度阶段失败：FailureHandler 调用 AddUnschedulableIfNotPresent 处理重新入队。
    • 插件拒绝且调度期间没有相关事件时，Pod 进入 unschedulablePods。
    • 插件拒绝且调度期间已经发生相关事件时，Scheduler 调用相应插件的 QueueingHint，判断该事件是否可能改变上次的调度结果，以及是否需要重新入队。
    • Scheduler Error 进入 podErrorBackoffQ 的重试路径。
  • 绑定阶段成功：API Server 保存绑定结果，Pod 进入 Bound 状态。
  • 绑定阶段失败：Scheduler 回滚本地状态，再由 FailureHandler 处理重新入队。

• 重新入队：SchedulingQueue 根据失败原因和相关集群事件安排 Pod 重试，先选择重试方式，再检查 Pod 当前是否满足入队条件。

  • 响应集群事件：Node、Pod、PVC 等对象变化时，SchedulingQueue 调用此前拒绝该 Pod 的插件为该事件注册的 QueueingHint。相关回调均返回 QueueSkip 时，Pod 继续留在 unschedulablePods；有回调返回 Queue 时，继续选择重试方式。

  • 选择重试方式：

    • 跳过退避：PendingPlugins 中有插件的 QueueingHint 返回 Queue 时，优先跳过退避。
    • 普通退避：仅其他拒绝插件的 QueueingHint 返回 Queue 时，根据剩余退避时间安排重试。
    • 错误退避：发生 Scheduler Error 时，失败处理直接选择错误退避方式，无需等待集群事件。

  • 处理停留超时：Pod 在 unschedulablePods 中停留超时时，定时任务 会触发重新入队检查，并按普通退避方式处理。

  • 检查并写入队列：启用 SchedulerPopFromBackoffQ 后，activeQ 为空时，Scheduler 可以直接从 podBackoffQ 取出 Pod，不必等待退避结束。因此，Pod 在进入退避队列前就要完成 PreEnqueue 检查，确保被取出时已经满足入队条件；检查规则与首次入队相同。检查未通过则转入 unschedulablePods；检查通过后，无需继续退避的 Pod 进入 activeQ，仍需普通退避或错误退避的 Pod 分别进入 podBackoffQ、podErrorBackoffQ。

PriorityQueue¶

Scheduler 创建过程中会调用 NewSchedulingQueue，得到默认实现 PriorityQueue。PriorityQueue 使用三个字段保存不同状态的 Pod：

• activeQ：现在可以尝试调度的 Pod。
• backoffQ：保存已经满足重新入队条件、但仍处于退避期的 Pod。podBackoffQ 保存插件拒绝后等待普通退避结束的 Pod；podErrorBackoffQ 保存发生 Scheduler Error 后等待错误退避结束的 Pod。
• unschedulablePods：保存尚未满足重新入队条件的 Pod，等待可能改变上次调度结果的集群事件。

type PriorityQueue struct {
    // ...

    // activeQ 保存当前可以调度的 Pod。
    activeQ  activeQueuer
    // backoffQ 保存仍处于退避时间内的 Pod。
    backoffQ backoffQueuer

    // unschedulablePods 等待可能改变调度结果的集群事件。
    unschedulablePods *unschedulablePods
}

activeQ¶

activeQueue 使用 Heap 保存可立即调度的 Pod，并记录正在调度的 Pod、调度期间发生的事件和调度周期序号：

type activeQueue struct {
    // 保护 activeQ、inFlightPods、inFlightEvents 和 schedCycle 等字段。
    lock sync.RWMutex

    // 保存可以立即调度的 Pod，Heap 队首是下一次取出的 Pod。
    queue *heap.Heap[*framework.QueuedPodInfo]
    // 包装同一个 Heap，供已经持有 lock 的代码调用。
    unlockedQueue *unlockedActiveQueue

    // 新 Pod 进入 activeQ 时唤醒正在等待的 Pop()。
    cond sync.Cond

    // 记录已经取出、但尚未结束本次调度处理的 Pod。
    inFlightPods map[types.UID]*list.Element
    // 记录这些 Pod 调度期间到达的集群事件，失败时用于判断是否立即重新入队。
    inFlightEvents *list.List

    // 每取出一个 Pod 增加一次，用于标识调度周期。
    schedCycle int64
    // Queue 关闭后，使正在等待的 Pop() 退出。
    closed bool

    isSchedulingQueueHintEnabled bool
    metricsRecorder              *metrics.MetricAsyncRecorder

    // 启用 SchedulerPopFromBackoffQ 时，允许 activeQ 为空后从 podBackoffQ 取出 Pod。
    backoffQPopper backoffQPopper
}

Scheduler 从 Profile 取得 QueueSortFunc，作为 lessFn 传入 NewPriorityQueue；该比较函数决定 Heap 的 Pod 顺序：

func NewPriorityQueue(
    lessFn fwk.LessFunc,
    informerFactory informers.SharedInformerFactory,
    opts ...Option,
) *PriorityQueue {
    // QueueSort 提供的 LessFunc 接收 fwk.QueuedPodInfo，
    // 这里转换为内部 *framework.QueuedPodInfo 的比较函数。
    lessConverted := convertLessFn(lessFn)

    // activeQ 使用 Heap 保存 Pod，队首由 QueueSort 的比较结果决定。
    pq.activeQ = newActiveQueue(
        heap.NewWithRecorder(
            podInfoKeyFunc,
            heap.LessFunc[*framework.QueuedPodInfo](lessConverted),
            metrics.NewActivePodsRecorder(),
        ),
        isSchedulingQueueHintEnabled,
        options.metricsRecorder,
        backoffQPopper,
    )
    // ...
}

新 Pod、已完成退避的 Pod，以及被相关事件重新激活的 Pod 都可以进入 activeQ。PriorityQueue.Pop() 调用 activeQueue.pop 取出队首 Pod；随后由 unlockedMovePodToInFlight 增加调度尝试次数、记录 inFlightPods 并递增调度周期序号。

backoffQ¶

backoffQueue 以退避结束时间排序，并使用两个 Heap：

• podBackoffQ：保存带有 UnschedulablePlugins 或 PendingPlugins 记录、并被安排进入退避的 Pod。普通路径主要来自 Unschedulable 失败；Pending 插件关联的事件返回 Queue 时，Pod 会跳过退避并进入 activeQ。
• podErrorBackoffQ：保存没有上述插件记录、因 Scheduler Error 进入错误退避的 Pod。

backoffQueue.add 根据失败记录选择内部队列：

type backoffQueue struct {
    // 插件相关失败使用普通退避。
    podBackoffQ *heap.Heap[*framework.QueuedPodInfo]
    // Scheduler Error 使用单独的错误退避。
    podErrorBackoffQ *heap.Heap[*framework.QueuedPodInfo]
    // ...
}

func (bq *backoffQueue) add(logger klog.Logger, pInfo *framework.QueuedPodInfo, event string) {
    // ...

    // 没有记录 Unschedulable 或 Pending 插件，表示本次失败来自 Scheduler Error。
    if pInfo.UnschedulablePlugins.Len() == 0 && pInfo.PendingPlugins.Len() == 0 {
        bq.podErrorBackoffQ.AddOrUpdate(pInfo)
        // ...
        return
    }

    // 插件相关失败进入普通退避队列。
    bq.podBackoffQ.AddOrUpdate(pInfo)
    // ...
}

Kubernetes v1.36 默认启用 Beta 的 SchedulerPopFromBackoffQ。activeQ 为空时，activeQueue.unlockedPop 可以直接取出 podBackoffQ 的队首，即使它还没有到退避截止时间；podErrorBackoffQ 不会沿这条路径提前取出：