本文說明如何解決將節點新增至 Google Kubernetes Engine (GKE) 標準叢集時發生的問題。發生這些問題的部分情況包括叢集建立和節點集區建立,以及擴充事件期間。
如要解決 GKE Autopilot 叢集的問題,請參閱「排解 Autopilot 叢集問題」。
關於節點註冊
節點是 Compute Engine VM 執行個體,由 GKE 代表您建立。將新節點新增至 GKE 叢集時,必須向叢集的控制層註冊。這個程序稱為「節點註冊」或「節點啟動」,會在建立節點時發生。
節點註冊時機
建立節點時 (包括下列情況),系統會註冊節點:
節點註冊程序包括下列步驟:
- 系統會將為節點集區設定的節點數量,複製到代管執行個體群組 (MIG)。
- MIG 會建立所需數量的 VM 執行個體。
針對建立的每個 VM 執行個體:
- VM 執行個體會啟動。
- VM 執行個體會設定並安裝必要套件,以做為 Kubernetes 節點執行。
- 在 VM 執行個體上執行的 kubelet 現在會與控制層的 API 伺服器通訊,以註冊為節點。
節點註冊錯誤訊息
如果節點註冊失敗,當 GKE 嘗試將節點新增至叢集時, Google Cloud 控制台會顯示下列錯誤:
All cluster resources were brought up, but: only 0 nodes out of * have
registered; this is likely due to the Nodes failing to start correctly; try
re-creating the cluster or contact support if that doesn't work.
這則錯誤訊息表示節點未成功向叢集註冊。以下各節說明這項錯誤的可能原因。
成功註冊節點的必要條件
節點能否成功註冊至 GKE 叢集,取決於下列因素:
- 網路連線。
- 資源可用性。
- 服務帳戶權限。
建立執行個體的必要條件
GKE 為叢集建立節點時,第一步是建立新的 Compute Engine VM 執行個體。
建立執行個體失敗的可能原因如下:
如果執行個體建立失敗,表示在 GKE 嘗試建立執行個體並註冊為 GKE 節點的時間範圍內,由於執行個體從未建立,因此缺少執行個體建立記錄。如要檢查是否有遺失的記錄,請參閱找出節點註冊失敗的執行個體操作說明。
服務帳戶權限
GKE 節點會與 IAM 服務帳戶建立關聯。根據預設,這個服務帳戶是 Compute Engine 預設服務帳戶。為強化叢集安全,建議使用具備最低必要權限的自訂 IAM 服務帳戶。
這個服務帳戶必須具備正確的權限,才能將 VM 執行個體初始化為 GKE 節點。如果刪除服務帳戶、停用服務帳戶,或未授予服務帳戶適當權限,節點註冊作業可能會失敗。
連線至 Google API 和服務的網路連線必備條件
VM 執行個體會下載套件,準備做為 GKE 節點執行,而連線逾時可能表示叢集未符合連線至 Google API 和服務 (例如 storage.googleapis.com
) 的必要網路條件。如果執行個體無法連線至這些服務,就無法下載 Kubernetes 發行版本,也無法完成節點註冊程序。
視網路連線而定,允許這項連線可能表示設定私人 Google 存取權,或在叢集的虛擬私有雲 (VPC) 網路中,擁有允許連線的防火牆規則和路徑。
與控制層建立網路連線的事前準備
控制層與節點之間的連線對於節點註冊和正常運作至關重要。這類通訊內容預設為允許。 請確保設定虛擬私有雲防火牆規則後,節點和控制層之間仍可通訊。
詳情請參閱「允許控制層連線」。
使用節點註冊檢查工具排解節點註冊問題
節點註冊檢查工具會在新建執行個體上執行,並檢查執行個體是否已順利完成節點註冊步驟。
如果節點註冊失敗,公用程式會產生摘要報告,您可根據執行個體在程序中的失敗位置,查看未達成的必要條件。
請按照下一節的說明,找出節點註冊失敗的執行個體,並使用節點註冊檢查工具摘要瞭解失敗原因。
找出節點註冊失敗的執行個體
如果一或多個執行個體無法向 GKE 叢集的控制平面註冊為節點,您可以在 Google Cloud 控制台的「叢集詳細資料」頁面中,查看錯誤訊息,瞭解有多少執行個體註冊失敗。如果多個執行個體無法同時註冊,可能是因為相同的根本原因。因此,您可以利用其中一個失敗的執行個體,調查所有執行個體失敗的原因。
不過,由於執行個體未註冊為 GKE 節點,您必須按照下列操作說明,找出註冊失敗的基礎 Compute Engine VM 名稱。
前往 Google Cloud 控制台的「Logs Explorer」頁面:
使用下列記錄篩選器,找出 VM 執行個體建立作業的記錄:
resource.type="gce_instance" logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity" protoPayload.requestMetadata.callerSuppliedUserAgent="GCE Managed Instance Group for GKE" protoPayload.response.status="RUNNING"
將
PROJECT_ID
替換為叢集的專案 ID。使用記錄篩選器下方的直方圖,將時間範圍縮小至節點應已建立的時間。
按一下「Query results」(查詢結果) 下方顯示的其中一個記錄,然後按一下「Expand nested fields」(展開巢狀欄位),即可顯示更多詳細資料。
找到
protoPayload.resourceName
欄位。路徑的最後一部分就是執行個體名稱。執行個體名稱的格式會以叢集名稱和節點集區名稱開頭,例如:gke-cluster-1-default-pool-b0ac62d3-9g1v
是gke-cluster-1
中default-pool
節點集區的執行個體。前往 Google Cloud 控制台的 Compute Engine「VM instances」(VM 執行個體) 頁面:
使用篩選條件找出 VM 執行個體的名稱。按一下即可瞭解詳情。
使用節點註冊檢查工具排解執行個體問題
找出無法註冊的執行個體名稱後,您可以使用節點註冊檢查工具,調查失敗原因。
在 VM 執行個體的「詳細資料」分頁中,按一下「記錄」專區中的「序列埠 1 (主控台)」。
新建立的執行個體輸出內容會包含下列項目,表示節點註冊檢查程式已啟動:
** Starting Node Registration Checker **
** Loading variables from kube-env **
** Sleeping for 7m to allow registration to complete **
如果節點註冊成功,輸出內容會包含下列訊息:
** Node ready and registered. **
** Completed running Node Registration Checker **
如果沒有看到這些訊息,表示節點註冊失敗,節點註冊檢查工具會產生報告,說明註冊失敗的原因。如要查看摘要,請尋找下列其他訊息:
** Here is a summary of the checks performed: **
在這則訊息下方,尋找類似下方的表格:
------------------------------
Service DNS Reachable
------------------------------
LOGGING true true
GCR true true
GCS true true
Master N/A false
------------------------------
如果 LOGGING
、GCR
或 GCS
列為無法連線,請檢查節點註冊的服務帳戶權限,以及節點註冊的 Google API 和服務網路連線。
如果 Master
列為無法連線,請檢查節點註冊的控制層網路連線先決條件。
解決所有導致節點註冊失敗的問題後,請參閱「修正根本原因後完成節點註冊」。
如果上述步驟無法說明節點註冊失敗的原因,請參閱「收集資訊以供進一步調查」。
排解節點註冊問題 (不使用節點註冊檢查工具)
只有在您已檢查節點註冊成功的前提條件,並嘗試使用節點註冊檢查工具後,才建議採取這些步驟。
解決所有導致節點註冊失敗的問題後,請修正根本原因並完成節點註冊。
如果本頁的調查步驟都無法說明節點註冊失敗的原因,請參閱「收集資訊以供進一步調查」。
檢查節點註冊的服務帳戶權限
節點使用的服務帳戶必須具備節點註冊的必要權限。請按照下列操作說明,確認你已完成這些必要條件:
在 VM 執行個體的「詳細資料」分頁中,於「API 和身分管理」部分,找出「服務帳戶」欄位中的服務帳戶名稱。如果節點使用 Compute Engine 預設服務帳戶,名稱格式為
PROJECT_NUMBER-compute@developer.gserviceaccount.com
。這個服務帳戶必須具備最低必要權限。在序列主控台輸出內容中,檢查註冊是否成功。在 VM 執行個體的「詳細資料」分頁中,按一下「記錄」專區中的「序列埠 1 (主控台)」。
如果執行個體使用的服務帳戶具備正確權限,輸出內容會包含下列項目:
Started Download and install k8s binaries and configurations
Started Docker Application Container Engine.
Started Configure kubernetes node.
Reached target Kubernetes.
這些訊息會顯示在輸出內容的不同位置。也可能出現時間戳記或其他干擾內容,例如:
Starting [0;1;39mConfigure kubernetes node
。如果看到所有這些訊息,表示服務帳戶已符合必要條件。如果沒有看到這些訊息,可能是指派給 VM 執行個體的服務帳戶已遭刪除、停用,或沒有正確的權限。
檢查節點註冊的 Google API 和服務網路連線
使用 SSH 存取權檢查連線
如果您可透過 SSH 存取專案中的 VM 執行個體,也可以檢查 VM 執行個體是否與 Google API 和服務建立網路連線。
在 VM 執行個體的「詳細資料」分頁中,按一下「SSH」。
連線至 VM 執行個體的指令列後,請執行下列指令,檢查與 Google API 和服務的連線:
curl -m 5 -v https://storage.googleapis.com/generate_204
如果連線成功,輸出結果會與下列內容相似:
* Trying 142.250.148.128:443... * Connected to storage.googleapis.com (142.250.148.128) port 443 (#0) ... < HTTP/1.1 204 No Content < Content-Length: 0 < Cross-Origin-Resource-Policy: cross-origin < Date: Wed, 04 Jan 2023 00:58:41 GMT < * Connection #0 to host storage.googleapis.com left intact
如果連線失敗,輸出結果會與下列內容相似:
* Trying 142.250.148.128:443... * Connection timed out after 5000 milliseconds * Closing connection 0 curl: (28) Connection timed out after 5000 milliseconds
如果連線逾時,且傳回的 IP 位址位於
199.36.153.0/24
IP 位址範圍內,請確認叢集是否符合連線至 Google API 和服務的網路需求。如果連線逾時,且傳回的 IP 位址不在上述 IP 位址範圍內,請檢查防火牆規則是否封鎖輸出流量,或叢集虛擬私有雲網路中的路徑是否設定錯誤。保持與 VM 執行個體的 SSH 連線開啟,然後繼續前往下一節。
使用連線能力測試檢查連線,不必透過 SSH 存取
如果沒有 VM 執行個體的 SSH 存取權,請使用連線測試,確認 VM 執行個體已連線至 Google API 和服務。
建立及執行連線測試,將 VM 執行個體設為「來源」,並將
storage.googleapis.com TCP/443
設為「目的地」。使用測試結果檢查叢集的網路設定。
檢查節點註冊的控制層網路連線
如果您有專案中 VM 執行個體的 SSH 存取權,可以檢查 VM 執行個體是否與叢集的控制平面建立網路連線。
在 VM 執行個體的「詳細資料」分頁中,按一下「SSH」。
連線至 VM 執行個體的指令列後,請將叢集的控制平面端點儲存為環境變數:
source <(sudo grep KUBERNETES_MASTER_NAME /home/kubernetes/kube-env)
將
GET
要求傳送至控制層端點:curl -k -m 5 https://${KUBERNETES_MASTER_NAME}/version
如果輸出內容與下列內容相似,表示 VM 執行個體可以與控制平面建立連線:
{ "major": "1", "minor": "24", "gitVersion": "v1.24.7-gke.900", "gitCommit": "e35c4457f66187eff006dda6d2c0fe12144ef2ec", "gitTreeState": "clean", "buildDate": "2022-10-26T09:25:34Z", "goVersion": "go1.18.7b7", "compiler": "gc", "platform": "linux/amd64" }
如果輸出內容類似下列內容,表示 VM 執行個體無法與控制層建立連線:
curl: (28) Connection timed out after 5000 milliseconds
如果 VM 執行個體無法與控制層建立連線,請參閱 GKE 網路最佳做法一節,瞭解如何允許控制層連線。
修正根本原因後,完成節點註冊
解決阻礙節點註冊的問題後,後續步驟取決於失敗的背景:
- 如果在建立叢集時節點註冊失敗,請刪除叢集,然後再試一次。
- 如果叢集自動調整程式在擴充期間無法註冊節點,請等待 VM 執行個體再次嘗試註冊。
- 如果建立節點集區時節點註冊失敗:
- 如果已建立 VM 執行個體,請等待 VM 執行個體再次嘗試註冊。
- 如果未建立 VM 執行個體,請刪除節點集區,然後再試一次。
- 如果叢集大小調整作業導致節點註冊失敗,請重新執行指令來增加叢集大小。
- 如果節點註冊失敗 (不在作業範圍內,例如在修復作業期間),請等待 VM 執行個體再次嘗試註冊。
收集資訊以利進一步調查
如果無法解決節點註冊問題,可以按照下列指示收集額外資訊,協助 Cloud 客戶服務團隊進行調查。這些步驟需要透過 SSH 存取專案中的 VM 執行個體,並使用 COS 映像檔隨附的 sosreport
公用程式。
-
或者,如果節點未下載
sosreport
公用程式,且無法安裝,請執行下列指令手動收集偵錯資訊:sudo journalctl -u cloud-init-local --no-pager sudo journalctl -u cloud-init --no-pager sudo journalctl -u cloud-final --no-pager sudo journalctl -u cloud-config --no-pager sudo systemctl status kubelet sudo journalctl -u kubelet --no-pager sudo systemctl status kube-node-installation.service sudo journalctl -u kube-node-installation.service --no-pager sudo systemctl status kube-node-configuration.service sudo journalctl -u kube-node-configuration.service --no-pager
將這些資訊打包成 ZIP 檔,並在向 Cloud Customer Care 提交客服案件時附上。
後續步驟
如果無法在說明文件中找到問題的解決方法,請參閱「取得支援」一文,尋求進一步的協助, 包括下列主題的建議:
- 與 Cloud 客戶服務聯絡,建立支援案件。
- 在 StackOverflow 上提問,並使用
google-kubernetes-engine
標記搜尋類似問題,向社群尋求支援。你也可以加入#kubernetes-engine
Slack 頻道,取得更多社群支援。 - 使用公開問題追蹤工具回報錯誤或提出功能要求。