本文說明叢集健康狀態掃描器的常見問題,以及解決方法。
偵測到有效工作負載,因此掃描作業略過節點或停止
問題:掃描作業略過部分 GPU 節點,或在 TPU 節點集區的預檢期間停止,並回報偵測到執行中的工作負載。
原因:一或多個目標節點正在執行工作負載。
解決方法:清空或停止目標節點上的工作負載,然後重新執行掃描。詳情請參閱「確認目標節點處於閒置狀態」。
掃描作業因機器類型不一而停止
問題:掃描作業在預檢期間停止,並回報目標節點使用不同的機器類型。
原因:您在 --nodepools 旗標中指定的節點集區,或在 --partitions 旗標中指定的分區,並非全部使用相同的機器類型。舉例來說,單次掃描無法混合 GPU 和 TPU 節點集區,或 A3 Mega 和 A4 節點。
解決方法:為每種機器類型分別執行掃描。
因儲存空間權限錯誤而停止掃描
問題:掃描作業在預檢期間停止,並回報 Cloud Storage 錯誤。
原因:bucket 不存在,或寫入報表的主體沒有寫入 bucket 的權限。
解決方法:確認 bucket 存在,且主體具備 bucket 的 Storage 物件管理員角色。詳情請參閱「設定報表的 Cloud Storage bucket」。
指令列工具無法連線至叢集
問題:chs 指令列工具傳回驗證或連線錯誤。
原因:叢集缺少 kubeconfig 項目,或容器中沒有憑證。
解決方法:執行 gcloud container clusters get-credentials 指令,如「連線至叢集或執行個體」所述。接著,請按照「安裝叢集健康狀態掃描器」一文所述,確認 kubeconfig 檔案和 Google Cloud 憑證已掛接在容器中。
呼叫端沒有存取專案的權限
問題:chs 指令傳回下列錯誤:
ERROR: The caller doesn't have permission to access the project PROJECT_ID
原因:憑證遺失或過期,或有效身分不具備專案所需的 Identity and Access Management (IAM) 權限。
解決方法:使用使用者帳戶設定應用程式預設憑證:
gcloud auth application-default login
如果您也需要使用使用者帳戶 (而非服務帳戶) 驗證 Google Cloud CLI,請執行下列指令:
gcloud auth login --no-browser
GPU 測試回報驅動程式或硬體錯誤
問題:執行 nvidia-smi 或 dcgm 測試執行後,健康狀態報告顯示部分節點的狀態為 DEGRADED 或 INCOMPLETE。
原因:未偵測到節點上的 GPU、GPU 驅動程式無法運作,或 NVIDIA 資料中心 GPU Manager (DCGM) 偵測到硬體故障。
解決方法:查看本機輸出目錄或 Cloud Storage bucket 的工作區目錄中的診斷記錄。然後按照「修復健康狀態不良的節點」一文中的步驟操作。
網路測試回報頻寬不足或延遲時間過長
問題:健康狀態報告顯示,部分節點的集體通訊頻寬偏低或延遲時間偏高。
原因:在 GPU 上,這可能是因為一或多個節點上的 GPU、NVLink 連線或網路介面故障。在 TPU 上,這可能是因為一或多個節點上的 ICI 連結或 TPU 晶片故障。
解決方法:如果是 GPU,請使用 nccl-pairwise 測試結果,找出哪些節點涉及速度緩慢的節點組合。如果是 TPU,請查看健康狀態報告中的 tpu-collectives 和 tpu-network-stress 結果。然後按照「修復健康狀態不良的節點」一文中的步驟操作。
掃描停止後,資源仍會保留在叢集內
問題:chs 程序終止後,診斷工作或資源仍留在 Google Kubernetes Engine (GKE) 叢集。
原因:在 GKE 上,chs 程序必須在掃描期間持續執行,才能在掃描完成時清除資源。
解決方法:取消已停止的執行作業,或取消叢集上的所有執行作業,藉此移除剩餘工作並釋出節點:
chs cancel RUN_ID
如要取消叢集上的所有執行作業,請執行 chs cancel --all。
TPU 忙碌時,獨立 TPU 執行個體的掃描作業會失敗
問題:在獨立 TPU 執行個體上執行掃描時,chs 指令列工具會傳回 TPUs are busy 錯誤。
原因:TPU 執行個體上的其他程序正在使用 TPU 裝置。
解決方法:等待其他程序完成或停止,然後重新執行掃描。
在獨立 TPU 執行個體上掃描失敗,並顯示 memlock 限制錯誤
問題:在獨立 TPU 執行個體上執行掃描時,chs 指令列工具會回報 memlock 限制過低,或 TPU 測試需要 root 或無限制的 memlock 限制。
原因:目前使用者工作階段的鎖定記憶體位址空間 (memlock) 限制受到限制。
解決方法:以 root 使用者身分執行叢集健康狀態掃描器,或在執行掃描前提高 memlock 限制:
ulimit -l unlimited
容器在獨立 TPU 執行個體上失敗,無法存取主機
問題:使用容器映像檔對獨立 TPU 執行個體執行掃描時,chs 指令列工具會失敗,並顯示下列錯誤:
CHS runs in a container without access to the host
原因:在 TPU 執行個體的獨立模式中,容器必須共用主機 PID 命名空間,並掛接主機檔案系統,才能檢查及使用 /dev/vfio 下的 TPU 裝置。
解決方法:使用 --privileged、--pid=host 和 -v /:/host 旗標啟動容器。如需完整的 docker run 指令,請參閱「容器映像檔」。
套件安裝失敗,並顯示 Python 版本錯誤
問題:執行 pip install 時失敗,並顯示錯誤訊息:Package 'chs' requires a
different Python。
原因:您機器上的 python3 版本早於 3.12,這在 Slurm 登入節點和 TPU 執行個體上很常見。
解決方法:使用 uv 建立 Python 3.12 虛擬環境,並在沒有 root 權限的情況下安裝叢集健康狀態掃描器:
python3 -m venv uv-venv
uv-venv/bin/pip install uv
uv-venv/bin/uv venv --python 3.12 chs-venv
source chs-venv/bin/activate
uv-venv/bin/uv pip install git+https://github.com/GoogleCloudPlatform/cluster-health-scanner.git
未安裝 TPU 測試依附元件,因此掃描作業略過獨立 TPU 執行個體
問題:在獨立 TPU 執行個體上執行掃描時,chs run 會略過執行個體,並傳回下列警告:
The TPU test dependencies are not installed. CHS installs them only on Linux x86_64 with Python 3.12.
原因:叢集健康狀態掃描器 Python 套件是以 3.12 以外的 Python 版本安裝 (例如 Python 3.13)。在獨立 TPU 執行個體上,TPU 基準測試依附元件只會安裝在搭載 Python 3.12 的 Linux x86_64 上。
解決方法:使用 uv 在 Python 3.12 虛擬環境中重新安裝叢集健康狀態掃描器 (請參閱「套件安裝失敗,並顯示 Python 版本錯誤」),或使用叢集健康狀態掃描器容器映像檔。