你提交了一个 Kubernetes Job，然后等待它的 Pod 出现。一分钟过去了。又过了一分钟。Job 仍处于挂起状态，没有应用日志，甚至可能根本没有 Pod 可供检查。

在由 Kueue 管理的集群中，这完全可能是正常现象。Kueue 可能仍在判断该 Job 是否可以使用所请求的资源。有用的问题不仅是“为什么 Pod 处于 Pending 状态？”，首先应该是“Kueue 是否已准入该 Workload？”

Headlamp 的 Kueue 插件将这一排查过程带入 Headlamp UI。你无需通过多个命令和庞大的 YAML 对象来重建准入路径，而是可以从 Workload 开始，阅读其 condition 消息，并沿着链接依次查看 LocalQueue、ClusterQueue、ResourceFlavor 和 Cohort。

本文遵循这种以 Headlamp 为先的路径。命令行仅出现在一个简短的可选章节中，用于复现示例。

开始之前

你需要一个已安装 Kueue 的 Kubernetes 集群、一个 Headlamp 安装，以及 0.1.0-alpha Kueue 插件。你的 Kubernetes 身份必须被允许读取本文中使用的 Kueue 资源。

该 alpha 版本为 Kueue v1beta2 的 Cohort、ClusterQueue、LocalQueue、ResourceFlavor 和 Workload 提供只读视图。它不会添加自己的创建、编辑、停止、恢复或删除工作流。在你的权限允许的情况下，Headlamp 仍会提供其标准的 YAML 和资源操作。

首先，将准入与 Pod 调度区分开

Kueue 和 Kubernetes 调度器回答的是不同的问题。

• Kueue 准入：考虑到队列策略、配额、ResourceFlavor、准入检查以及其他等待中的 Workload，该 Workload 现在应该启动吗？

• Pod 调度：在 Workload 被准入且 Job 恢复后，哪些节点可以运行其 Pod？

这一边界改变了排查方向。如果 Workload 未被准入，请留在 Headlamp 的 Kueue 部分。如果它已被准入但其 Pod 仍处于 Pending 状态，请转到 Headlamp 的常规 Job 和 Pod 视图，并检查调度器事件。

以 Headlamp 为先的故障排查路径

最快的排查从 Workload 开始，而不是从 shell 开始。

步骤 1：打开 Workloads 视图

在 Headlamp 中，打开 Kueue → Workloads。选择包含该 Job 的命名空间，然后找到为其创建的 Workload。

Kueue 会创建一个 Workload 来表示 Job 的资源请求和准入状态。在 alpha 插件中，owner references 显示为 Kind/name 文本，但尚不可点击。Workload 名称通常包含 Job 名称，因此命名空间过滤和表格搜索是定位它的最简单方法。

在打开详情页之前，列表已经为你提供了有用的初步扫描信息：

• LocalQueue

• priority 和 priority class

• active 状态

• admitted 状态

• completion 状态

• 可读的当前状态，例如 Admitted、Finished 或 Inadmissible

• age

如果没有匹配的 Workload，在继续之前请检查三件事：所选命名空间、Job 是否提交到 LocalQueue，以及你的 Kubernetes 账户是否可以列出 Workloads。该插件会执行权限检查，并在当前身份无法读取资源时显示访问消息。

步骤 2：读取状态、条件和事件

打开 Workload。从其当前状态和条件开始，而不是从完整的 YAML 开始。

对于准入排查，最重要的条件类型是 QuotaReserved 和 Admitted。

• Admitted=True 表示 Kueue 已准入该 Workload。Job 可以恢复，因此任何剩余的 Pending Pod 都属于排查的调度分支。

• QuotaReserved=False 且原因为 Pending 等，表示 Kueue 尚未预留配额。条件消息解释了阻止预留的原因。

• Inadmissible 状态表示该 Workload 当前无法适配可用的队列配置。缺少 covered resource、ResourceFlavor 不合适、队列已停止或准入检查都可能导致此状态。

例如，条件消息可能报告 Kueue 无法分配 ResourceFlavor，因为 ClusterQueue 的 CPU 配额不足。该消息是对“为什么我的 Job 仍处于 pending 状态？”的第一个真正答案。Headlamp 旅程的其余部分解释了其背后的配置。

同时检查 Events 部分。Conditions 描述当前状态；events 有助于显示最近发生了什么变化或 Kueue 尝试了什么。

步骤 3：比较 Workload 的请求与其分配

停留在 Workload 详情页，检查 PodSets 和资源请求。该插件显示请求的 Pod 数量、CPU、内存以及 Kueue 一起评估的其他资源。

这一点很重要，因为一个 parallelism: 3 且每个 Pod 请求一个 CPU 的 Job 会向 Kueue 请求总共三个 CPU。仅查看一个 Pod 的模板会低估该 Workload。

如果配额已被预留，同一页面还会显示分配的 ClusterQueue、ResourceFlavors 和已准入的资源使用量。如果这些准入分配缺失，则 Workload 尚未达到该阶段。

在我们的示例中，Workload 请求：

• 三个 Pod

• 总共三个 CPU

• 总共 600 MiB 内存

下一个问题是该请求从何处进入 Kueue。

步骤 4：跟踪关联的 LocalQueue

使用 Workload 详情页上的 LocalQueue 链接。LocalQueue 是 Job 使用的命名空间级入口点。它将命名空间级的 Workload 连接到集群级的 ClusterQueue。

LocalQueue 页面显示：

• 其命名空间和连接的 ClusterQueue

• 停止策略和当前状态

• 待处理、预留中和已准入的 Workload 数量

• Kueue 条件和 Kubernetes 事件

• 同一命名空间中的相关 Workload

本页回答两个实际问题：Job 是否进入了预期的队列，以及它是否是队列中唯一等待的 Workload？

如果 LocalQueue 处于非活跃或已停止状态，这可能已经解释了等待的原因。如果它处于活跃状态，请沿着链接的 ClusterQueue 检查其背后的容量。

步骤 5：检查 ClusterQueue 容量和使用情况

ClusterQueue 表示可供一个或多个 LocalQueue 使用的集群级配额和准入策略。

在其 Headlamp 详情页上，将 Workload 请求与以下内容进行比较：

• 覆盖的资源

• 每个 ResourceFlavor 的 nominal quota

• 当前预留和使用量

• 借用和出借限制

• 待处理、预留中和已准入的 Workload 数量

• 排队策略和停止策略

• 抢占、公平共享、flavor-fungibility 和准入检查设置

• Kueue 条件和 Kubernetes 事件

对于本文中的示例，ClusterQueue 提供的 nominal quota 为两个 CPU 和两个 Pod 槽位。Workload 请求各三个。条件消息和 ClusterQueue 页面现在说明了同一件事：Workload 无法容纳，因此 Kueue 让 Job 保持挂起状态。

这是一个准入容量问题。这并不能证明 kube-scheduler 未能找到节点。

步骤 6：在需要时检查 ResourceFlavor 和 Cohort

配额并不总是一个单一的池。ResourceFlavor 可以通过节点标签、污点、容忍度或拓扑设置来表示一类计算资源。当条件提到 flavor 分配，或者当 Workload 需要特定硬件类别（例如 GPU 节点）时，请使用 ClusterQueue 中的 ResourceFlavor 链接。

如果 ClusterQueue 属于某个 Cohort，也请沿着该链接查看。Cohort 允许 ClusterQueue 共享未使用的配额。Headlamp 页面显示父级和子级 Cohort、成员 ClusterQueue、引用的 ResourceFlavor、资源组、借用和出借限制以及公平共享信息。

这些页面有助于回答一个更微妙的问题：Workload 被阻塞是因为队列本身没有配额、是因为它无法借用足够的配额，还是因为无法分配合适的 flavor？

无需离开 Headlamp 就能了解到的情况

对于示例中处于 pending 状态的 Job，UI 给出了完整的解释：

• 该 Workload 未被准入。

• 其 QuotaReserved 条件为 false，消息指出配额不足。

• 该 Workload 请求三个 CPU 和三个 Pod 槽位。

• 其 LocalQueue 处于活动状态，并指向预期的 ClusterQueue。

• 该 ClusterQueue 仅提供两个 CPU 和两个 Pod 槽位。

• 因此，Kueue 会保持该 Job 挂起，直到配额可用或队列配置发生变化。

关键之处不在于 Headlamp 发明了新的状态。它读取的是与其他客户端相同的 Kubernetes API 对象，然后将相关资源和人类可读的值放在一个连贯的调查视图中。

如果 Workload 已被准入，请切换视图

假设 Workload 详情页显示 Admitted=True，但应用仍未运行。Kueue 已完成其决策部分。请继续在 Headlamp 的标准 Kubernetes 视图中排查：

• 打开 Workloads → Jobs，检查 Job 状态和事件。

• 打开 Workloads → Pods，按 Job 名称或命名空间过滤。

• 选择一个 Pending 的 Pod，阅读其 Events 部分。

在此阶段，请查找调度器相关的问题，例如节点容量不足、node affinity、taints 和 tolerations、拓扑约束、持久卷绑定或镜像拉取失败。

这种交接是本文中最有用的故障排查规则：

• 未被准入：在 Headlamp 中调查 Kueue 资源。

• 已准入，但 Pod 处于 Pending：在 Headlamp 中调查 Job、Pod、节点和调度器信息。

可重复使用的 Headlamp 检查清单

当下一个 Job 无法启动时，请使用这条简短路径：

• 打开 Kueue → Workloads 并选择正确的命名空间。

• 找到与 Job 关联的 Workload。

• 检查可读状态、Admitted 和 QuotaReserved 条件。

• 阅读条件消息和最近事件。

• 将 PodSet 资源请求与任何准入分配进行比较。

• 跟随 LocalQueue 链接并确认其状态和 ClusterQueue。

• 跟随 ClusterQueue 链接并比较配额、预留、使用情况和策略。

• 当消息指向 flavor 选择或共享配额时，检查 ResourceFlavor 或 Cohort 详情。

• 如果已准入，转到 Headlamp 的 Job 和 Pod 视图。

在此调查过程中 Headlamp 替代了什么

该插件不会替代 kubectl 或 kueuectl 用于脚本、精确对象输出或变更。它替代的是交互式调查期间所需的重复性无 UI 导航。

| 问题 | Headlamp 路径 | 命令行等效项 |
| --- | --- | --- |
| Workload 是否已准入？ | Kueue → Workloads → 状态和条件 | kubectl describe workload-n|
| 它进入了哪个 LocalQueue？ | Workload → 链接的 LocalQueue | kubectl get localqueue-n-o yaml |
| 哪个 ClusterQueue 提供配额？ | LocalQueue → 链接的 ClusterQueue | kubectl get clusterqueue-o yaml |
| 哪个 flavor 或共享配额重要？ | ClusterQueue → ResourceFlavor 或 Cohort | kubectl get resourceflavor-o yaml 或 kubectl get cohort-o yaml |
| 准入后发生了什么？ | Workloads → Jobs 和 Pods → 事件 | kubectl describe job-n或 kubectl describe pod-n|

对于脚本和 GitOps 工作流，命令行仍然是正确的工具。对于询问“为什么这个在等待？”的人来说，链接的 Headlamp 路径通常阅读起来更快。

可选：复现待处理场景

插件仓库包含用于本地测试的示例 Cohort、ClusterQueue、LocalQueue、ResourceFlavor 和 Job 清单。将这些示例应用到已安装 Kueue 的集群，然后在 Headlamp 中打开 Kueue 部分。

要复现本文中使用的特定配额不匹配，请配置一个具有两个 CPU 和两个 Pod 槽位的 ClusterQueue，然后提交一个请求每个 Pod 一个 CPU 的三 Pod Job。该 Job 进入其 LocalQueue，Kueue 创建一个 Workload，并且由于合并请求大于可用配额，Workload 保持待处理状态。

将此设置与主要演练分开是有意为之：一旦资源存在，调查本身应在 Headlamp 中进行。

当前 alpha 限制

0.1.0-alpha 版本是 Kueue 准入路径的初始只读视图。

• 该插件不添加自己的创建、编辑、暂停、恢复或删除流程。

• Workload 所有者引用显示为文本，目前不可导航。

• UI 依赖于 Headlamp 使用的身份所具有的 Kubernetes 权限。

• 指标和可视化关系图是可能的后续领域，而不是此版本的功能。

明确说明这些限制是有用的：该插件当前的目的是让准入状态和资源关系更容易被检查。

在 LFX Mentorship 期间开发

该插件是在 CNCF LFX Mentorship 2026 Term 2 期间使用 TypeScript、React、Kubernetes API 和 Headlamp 的插件系统开发的。

Utkarsh Raj 在 René Dudfield（@illume）和 Kevin Hannon（@kannon92）的指导与评审下实现了该插件。来自 Headlamp 和 Kueue 社区的反馈塑造了资源视图、状态呈现、导航、文档、测试以及首个 alpha 版本。

浏览插件源码和 README，阅读 0.1.0-alpha 发布文档，或在发布 issue 中分享反馈。

如果按照 Headlamp 的路径操作后，仍难以解释某个待处理的 Workload，那正是可以改进该插件的反馈类型。

转载声明：本文为转载整理，原文版权归原作者及原站点所有。

原文来源：Kubernetes Blog

原创地址：https://kubernetes.io/blog/2026/10/14/tracing-kueue-admission-with-headlamp/