下面两张图从同一份链路的不同视角呈现完整流程:横版以 CQ 为行、阶段为横轴,看多队列如何并行决策与互借(可左右拖动); 纵版沿主干自上而下,逐层看每一步判定。两张图与正文 8 阶段一一对应。
提交作业前,管理员先建好一整套资源治理对象:ResourceFlavor(资源"口味",用 nodeLabels 圈定一类节点)、ClusterQueue(集群级配额池)、LocalQueue(命名空间提交入口)、可选 Cohort(可互借配额的队列组)。配额数量只写在 ClusterQueue 里,Flavor 本身不定义数量。
# kueue.x-k8s.io/v1beta1 apiVersion: kueue.x-k8s.io/v1beta1 kind: ResourceFlavor metadata: {name: spot-gpu} spec: nodeLabels: cloud.google.com/gke-spot: "true" # 圈定 spot 节点 tolerations: - {key: spot, operator: Equal, value: "true"}
nodeLabels 是 Flavor 的核心,准入时会被注入成 Pod 的 nodeSelector,把逻辑配额和真实节点缝合起来。用户提交的是作业对象(Job / JobSet / PyTorchJob 等)。在 Job 上打 kueue.x-k8s.io/queue-name label 指向 LocalQueue;不打则用 namespace 级默认 LocalQueue;两者都没有就不被接管。
# batch/v1.Job apiVersion: batch/v1 kind: Job metadata: name: job-a labels: kueue.x-k8s.io/queue-name: lq-a1 # ← 归属 LocalQueue spec: parallelism: 4 # ← 4 个 Pod template: spec: priorityClassName: high-priority # ← 排序/抢占用 containers: [...]
kueue.x-k8s.io/queue-name;Kubeflow 类 suspend 字段在 spec.runPolicy.suspend。Kueue 的 mutating admission webhook 在 Job CREATE 时拦截,把工作负载对象本身的 suspend 字段设为 true。挂起的是作业对象,不是 Pod,也不是 Workload。Pod 由 Job Controller 看到 suspend 后自然不创建。
# webhook patch 后的 Job spec: suspend: true # batch/v1.Job # JobSet: spec.suspend # PyTorchJob: spec.runPolicy.suspend # RayJob: spec.suspend
ClusterQueue 用 resourceGroups 引用 Flavor,并为每个 (资源, flavor) 二维组合分配配额。配额可借用、可抢占,构成调度的坐标轴。
spec:
resourceGroups:
- coveredResources: ["cpu", "nvidia.com/gpu"]
flavors:
- name: spot-gpu
resources:
- {name: cpu, nominalQuota: 80}
- {name: nvidia.com/gpu, nominalQuota: 4, borrowingLimit: 2}
- name: on-demand
resources:
- {name: cpu, nominalQuota: 20, lendingLimit: 10}
cpu,在 spot 池 80 核、on-demand 池 20 核,分别扣减互不相干。suspend=true 冻住的 Job,以及管理员配好的 Flavor / ClusterQueue / LocalQueue / Cohort。此时还没有 Workload,也没有任何 Pod。只保留调度器需要的东西:资源诉求(podSets)+ 队列归属(queueName)+ 优先级(priority),剥掉镜像、命令、卷等执行细节——虽然 template 里带着,但调度器只看资源。
Workload 的 ownerReferences 指向 Job,保证 Job 删除时 Workload 级联消失。同步 decisions 与 statuses,全程不直接操作 Job 之外的对象。
Kueue 从不创建 Pod、也不直接碰 Pod。它只操作 Workload + 改 Job 的 suspend。Pod 的生死由 Job Controller 根据 suspend 决定——这是贯穿全局的统一边界。
apiVersion: kueue.x-k8s.io/v1beta2
kind: Workload
metadata:
name: job-a
namespace: team-a
ownerReferences: [{kind: Job, name: job-a}] # 级联
spec:
active: true
queueName: lq-a1 # ← LocalQueue
priority: 100 # ← PriorityClass 解析值
podSets: # ← 可含多个:main / worker
- name: main
count: 4 # parallelism=4
template: # PodSpec(含 requests)
spec: {containers: [...]}
master×1 + worker×8 两个 podSet,所有 podSet 被当作一个原子单元准入——这正是 Gang Scheduling 的基础。podSet.count × requests 可计算,下一步由调度器判定配额。官方原话:queueingStrategy 决定 Workload 如何 ordered in the ClusterQueue。排序键 = priority → creationTimestamp,与具体 podSet 无关。Workload 先进 LocalQueue,但跨该 CQ 下所有 LQ 一起排——因为配额池在 CQ 层。
StrictFIFO:队头装不下就阻塞后面全部(队头阻塞)。BestEffortFIFO(默认):队头装不下就跳过它,放行能装下的新 Workload 保吞吐。一个周期可取多个 Workload 准入,不是只处理一个。
两个 CQ 的 spec.cohort 同名才互借。借的是组内成员未用的 nominalQuota,先用自己的、用完才借。borrowingLimit 限最多借入,lendingLimit(v0.17 stable)限最多借出。
原主人有 pending 作业时,通过 reclaimWithinCohort 抢占策略收回借出的份额,优先保障各成员自身 nominalQuota。借用有 flavor 限制:只能借自己定义过的 flavor。
| 队列层级 | 作用域 | 角色 | 关键字段 |
|---|---|---|---|
| LocalQueue | 命名空间 | 用户提交入口,按 priority 入队 | spec.clusterQueue 指向上层 |
| ClusterQueue | 集群 | 真正配额池,排序 + 准入判定的发生地 | resourceGroups / queueingStrategy |
| Cohort | 多个 CQ | 允许成员互借闲置配额,提升利用率 | spec.cohort 同名归组 |
Kueue 把每个 podSet 的容器 requests 乘以 count 再累加得到 Workload 的总诉求。请求值会按 LimitRange 默认值、RuntimeClass overhead、仅 limits 当 requests 等规则调整,校验不过标记 Inadmissible。
配额、借用、抢占、nodeSelector 注入全都挂在 (资源, flavor) 这个二维单位上。多 flavor 配合 flavorAssignmentMode 可实现"优先便宜 spot,不够回退按需"的成本优化。
配额够 → 可直接准入。
本队列内有更低优先级可抢。
配额被同 Cohort 其他队列借走,要回来。
谁都让不出 → 继续 Pending 等待。
候选排序:借用的队列 → 最低优先级 → 最近准入。逐个累加受害者资源凑够缺口即停,只抢刚好够的最小集合。受害者必须优先级严格小于自己,且受策略边界约束。
必须先经过直接准入失败、FIFO 排序判定,才进入抢占轮。默认三种策略均为 Never——不配置就不会抢,体现"尽量不冲击已有工作"的设计。
被抢 Workload 重新入队(带 backoff),配额释放后重新走准入校验,确认额度真的腾出才放行抢占者。
Workload 保持 Pending,等待后续周期;公平共享(Fair Sharing)会偏向 share 低的队列准入、偏向 share 高的队列抢占。
调度器已在目标 CQ 的 ResourceGroups 里锁定资源(= Workload scheduling,≠ Pod scheduling)。
启用拓扑感知时,确认所有 Pod 能真正放进目标拓扑域(block/rack),消除"总量够但碎片放不下"。
所有(可选)AdmissionCheckStates 处于 Ready 状态,外部配额系统放行。
调度器选中 flavor 后,把该 flavor 的 nodeLabels 注入成 Pod 的 nodeSelector。这一步把"Kueue 逻辑配额"和"K8s 真实调度"缝合——保证 Pod 真落在对应类型节点上。
Reconciler 把 Job 的 suspend 置为 false,Job Controller 随即一次性创建出全部 Pod。Workload status 增加 QuotaReserved、Admitted 等 conditions。
所有 Pod 就绪(已调度 + 运行中 + 通过可选就绪探针)→ Workload condition PodsReady=True → 保持 Admitted 稳定运行。Job 完成后 Workload 被删除,配额归还 ClusterQueue,调度器继续处理下一个(可抢占低优先级任务)。
若 timeout(默认 5 分钟,较新版本 1 小时)内未全 Ready:撤销准入 → Job 重新 suspend → Workload 带 backoff 重新排队,配额释放。blockAdmission 可串行放行防两个半调度作业互锁。
| 状态字段 / 事件 | 含义 |
|---|---|
status.requeueState.count / requeueAt | 因 PodsReadyTimeout 被驱逐后的指数退避重排次数与下次入队时间 |
status.schedulingStats.evictions[] | 按 reason(Preempted / PodsReadyTimeout / Deactivated)+ underlyingCause 记录驱逐历史,支撑 metrics |
spec.active: false | 停用 Workload:运行中会被驱逐且不重排;maximumExecutionTimeSeconds 超时也会自动 deactivate |
status.reclaimablePods[] | 动态回收:声明某些 podSet 不再需要的配额,逐步释放(Dynamic Reclaim) |
| 类别 | 对象 / 字段 | 谁提供 |
|---|---|---|
| ① K8s 核心 | batch/v1 Job 的 .spec.suspend(1.22 GA) | Kubernetes 原生 |
| ② 第三方框架 CRD | JobSet .spec.suspend · PyTorchJob/TFJob .spec.runPolicy.suspend · RayJob .spec.suspend | 微软 / Kubeflow / KubeRay 社区 |
| ③ Kueue 自有 CRD | Workload · ClusterQueue · LocalQueue · ResourceFlavor · Cohort · AdmissionCheck · Topology · WorkloadPriorityClass | Kueue 项目(无 suspend 概念) |
所有 PodSet 的配额能一次性同时预留才 unsuspend;默认不部分准入。这是 Gang 的第一层。
准入前检查所有 Pod 能否真放进目标拓扑域,消除"总量够但碎片化放不下"——经典场景:8 卡分散在两台 4 卡节点,8 卡 Pod 永远卡住。
放行后监控全 Pod Ready,超时未全 Ready → 撤销准入、驱逐重排。启发式:不阻止部分调度,但保证不会永久占着资源。
自动扩缩容场景,等容量就绪后才准入,配合 Cluster Autoscaler 避免"配额有了但节点还没起来"。
podSetUpdates/minCount)才允许部分准入,用于可缩容训练,非默认。| 维度 | StrictFIFO | BestEffortFIFO(默认) |
|---|---|---|
| 队头装不下时 | 阻塞后面所有 Workload,即使后面的更小 | 跳过队头,放行能装下的新 Workload |
| 取舍 | 严格顺序公平,可能队头阻塞 | 保吞吐,可能"后来居上" |
| 抢占策略 | 可选值 | 默认 |
|---|---|---|
reclaimWithinCohort | Never / LowerPriority / Any | Never |
borrowWithinCohort | Never / LowerPriority / Any | Never |
withinClusterQueue | Never / LowerPriority / LowerOrNewerEqualPriority | Never |
borrowingLimit / lendingLimit 在 v1beta1 里曾是 alpha(默认门关),lendingLimit 自 v0.17 起 stable。TAS 自 v0.14 起 beta 默认开启。查文档/面试时注意版本差异。以「3 个 Job / 3 个 LocalQueue / 2 个 ClusterQueue(同 Cohort)」为背景。上面 8 阶段讲「从提交到落地的生命周期」,这里两张图讲「一个 reconcile 周期内部怎么转」。