Job 卡在 Pending：先查 Kueue 有沒有 admit，再用 Headlamp 逐層追
Kubernetes Blog · 2026-10-14
Kueue 叢集裡 Job 遲遲不起來時，第一個要問的不是「Pod 為什麼 Pending」，而是「Kueue 有沒有 admit 這個 Workload」。Headlamp 新增的 Kueue 外掛（0.1.0-alpha）把這條追查路徑做成 UI：從 Workload 一路點到 LocalQueue、ClusterQueue、ResourceFlavor 與 Cohort，取代原本要在多個 kubectl get -o yaml 之間手動對照的做法。
這篇由 LFX Mentee Utkarsh Raj 與 René Dudfield、Kevin Hannon 於 2026-10-14 發表在 Kubernetes 官方部落格。外掛目前只讀，支援 Kueue v1beta2 的 Cohort、ClusterQueue、LocalQueue、ResourceFlavor 與 Workload。
原本的問題
Job 被 Kueue 管理後，會先處於 suspended 狀態，沒有 Pod，也沒有應用程式 log。Kueue 不直接操作 Job，而是為每個 Job 建立一個 Workload 物件，Workload 才是 admission 的單位，決定結果再同步回 Job。
很多人在這時直接去查 Pod 或 scheduler 事件，查不到東西，因為 Pod 根本還沒建立。正確的分界線是：Kueue 管「這個 Workload 現在該不該開始」（queue 政策、配額、ResourceFlavor、admission check、其他排隊中的 Workload）；kube-scheduler 管「admit 之後 Pod 放哪個節點」。
Headlamp 上的追查路徑
文章的建議順序是由 Workload 往上游走。
- Workload 的 conditions：先看
QuotaReserved與Admitted，不要先讀整份 YAML。QuotaReserved=False搭配 reasonPending表示尚未保留配額，condition message 會說明原因。列表上的狀態若是Inadmissible，代表目前的 queue 設定放不下它。 - PodSet 的總需求：Kueue 是整體計算。文章範例是
parallelism: 3、每個 Pod 要 1 CPU，Workload 就是 3 個 Pod、共 3 CPU、共 600 MiB 記憶體，只看單一 Pod 的 template 會低估。 - LocalQueue：namespace 層級的入口，確認 Job 進了預期的 queue、queue 沒被停用，以及同 namespace 還有多少 Workload 在排隊。
- ClusterQueue：比對 nominal quota、目前保留量與用量、borrowing 與 lending 上限，以及 preemption、fair-sharing、flavor-fungibility 設定。
- ResourceFlavor 與 Cohort：message 提到 flavor 指派失敗，或需要特定硬體（例如 GPU 節點）時才往下看；Cohort 則用來判斷是自身沒配額、借不到，還是沒有合適的 flavor。
文章中的範例
範例的 ClusterQueue 只有 2 CPU 與 2 個 Pod slot，Workload 要 3 與 3。Workload 的 condition message 與 ClusterQueue 頁面講同一件事：放不下，所以 Kueue 讓 Job 繼續 suspended。這是 admission 容量問題，不是 kube-scheduler 找不到節點。要解就是等配額釋出，或改 queue 設定。
外掛本身沒有發明新狀態，讀的是和其他 client 相同的 Kubernetes API 物件，只是把相關資源與可讀數值串在同一條導覽路徑上。
對照指令與影響範圍
| 問題 | 等價指令 |
|---|---|
| Workload 有沒有 admit | kubectl describe workload <name> -n <ns> |
| 進了哪個 LocalQueue | kubectl get localqueue <name> -n <ns> -o yaml |
| 哪個 ClusterQueue 提供配額 | kubectl get clusterqueue <name> -o yaml |
| flavor 或共享配額 | kubectl get resourceflavor|cohort <name> -o yaml |
受影響的是在共用叢集上跑批次或訓練 Job 的使用者，以及維護 ClusterQueue 的平台團隊。遇到 Job 沒起來，先用 Workload 判斷分支：Admitted=True 但 Pod 仍 Pending，才轉去看 Job、Pod 事件與 taint、affinity、PV binding、image pull；沒 admit 就留在 Kueue 資源裡查。
要用這個外掛，Headlamp 使用的身分必須有權限讀取上述 Kueue 資源；缺權限時外掛會顯示存取訊息。腳本與 GitOps 流程仍應使用 kubectl 或 kueuectl，外掛不取代它們。
目前限制
- 純唯讀，不提供建立、編輯、暫停、恢復或刪除流程（Headlamp 原有的 YAML 與資源操作仍依權限可用）。
- Workload 的 owner reference 只顯示為文字，尚不能點擊，需用 namespace 篩選與搜尋找對應的 Workload。
- Metrics 與視覺化關係圖只是可能的後續方向，這個版本沒有。