Kueue 准入排查工具：Headlamp 插件可视化管理队列

提交一个 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 的 Cohorts、ClusterQueues、LocalQueues、ResourceFlavors 和 Workloads 提供只读视图。它不会添加自己的创建、编辑、停止、恢复或删除工作流。在你的权限允许的情况下，Headlamp 仍会提供其标准的 YAML 和资源操作。

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

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

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

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

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

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

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

在打开详情页之前，列表已经为你提供了有用的初步扫描： 可读的当前状态，例如 Admitted、Finished 或 Inadmissible

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

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

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

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

QuotaReserved=False 且原因为 Pending 之类，表示 Kueue 尚未预留配额。condition 消息会解释是什么阻止了预留。

QuotaReserved=True 但没有 Admitted=True，表示配额已预留，但一个或多个准入检查可能仍在等待中。在转向 Pod 调度之前，请检查该 Workload 的准入检查和消息。

Inadmissible 状态表示该 Workload 当前无法适配可用的队列配置。缺少覆盖资源、ResourceFlavor 不合适、队列已停止或准入检查，都可能导致这一状态。

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

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

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

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

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

下一个问题是该请求从哪里进入 Kueue。

使用 Workload 详情页上的 LocalQueue 链接。LocalQueue 是 Job 使用的命名空间级入口点。它将命名空间级的 Workloads 连接到集群级的 ClusterQueue。 pending、reserving 和 admitted 的 Workload 计数

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

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

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

在其 Headlamp 详情页上，将 Workload 请求与以下内容进行比较： pending、reserving 和 admitted 的 Workload 计数 抢占、公平共享、flavor-fungibility 和准入检查设置

对于本文中的示例，ClusterQueue 提供两个 CPU 和两个 Pod 槽位的 nominal quota。该 Workload 各请求三个。condition 消息和 ClusterQueue 页面现在讲述的是同一个故事：该 Workload 无法适配，因此 Kueue 让 Job 保持挂起。

（原文较长，此处译出前 6000 字，完整内容请点「打开原文」。）