排解 CrashLoopBackOff 事件

Autopilot Standard

如果 Google Kubernetes Engine (GKE) 中的 Pod 停滯在 CrashLoopBackOff 狀態，表示一或多個容器會重複啟動，然後結束。這種情況可能會導致應用程式不穩定或完全無法使用。

使用這個頁面診斷及解決根本原因，這些原因通常屬於資源限制、存活探查問題、應用程式錯誤或設定錯誤等類別。排解這些問題有助於確保應用程式穩定運作，並持續提供給使用者。

對於想找出並修正應用程式層級問題 (例如程式碼錯誤、進入點不正確、設定檔問題，或連線至依附元件的問題) 的應用程式開發人員來說，這項資訊非常重要。平台管理員和營運人員可以找出並解決平台相關問題，例如資源耗盡 (OOMKilled)、節點中斷或設定錯誤的存活探查。如要進一步瞭解我們在 Google Cloud 內容中提及的常見角色和範例工作，請參閱「常見的 GKE 使用者角色和工作」。

瞭解 CrashLoopBackOff 事件

如果 Pod 停滯在 CrashLoopBackOff 狀態，表示其中的容器會重複啟動、當機或結束。這個 CrashLoop 會觸發 Kubernetes，嘗試按照其 restartPolicy 重新啟動容器。每次重新啟動失敗後，下次嘗試前的 BackOff 延遲時間會以指數方式增加 (例如 10 秒、20 秒、40 秒)，最多可達五分鐘。

雖然這項事件表示容器內有問題，但也是有價值的診斷信號。CrashLoopBackOff 事件會確認 Pod 建立的許多基礎步驟 (例如指派給節點和提取容器映像檔) 都已完成。這項知識可讓您專注於調查容器的應用程式或設定，而非叢集基礎架構。

CrashLoopBackOff 狀態的發生原因，是 Kubernetes (具體來說是 kubelet) 會根據 Pod 的重新啟動政策處理容器終止作業。這個週期通常會遵循以下模式：

1. 容器啟動。
2. 容器會結束。
3. kubelet 會觀察停止的容器，並根據 Pod 的 restartPolicy 重新啟動容器。
4. 這個週期會重複，容器會在指數輪詢延遲時間增加後重新啟動。

Pod 的 restartPolicy 是這項行為的關鍵。預設政策 Always 是造成這個迴圈最常見的原因，因為即使容器成功結束，只要任何原因導致容器結束，系統都會重新啟動容器。OnFailure 政策只會在非零結束代碼時重新啟動，因此較不可能造成迴圈，而 Never 政策則會完全避免重新啟動。

找出 CrashLoopBackOff 事件的徵兆

狀態為 CrashLoopBackOff 的 Pod 是 CrashLoopBackOff 事件的主要指標。

不過，CrashLoopBackOff事件可能會有較不明顯的症狀：

• 工作負載沒有任何正常的副本。
• 健康副本數量急遽減少。
• 已啟用水平自動調度 Pod 資源功能的工作負載調度資源速度緩慢，或無法調度資源。

如果 system 工作負載 (例如記錄或指標代理程式) 處於 CrashLoopBackOff 狀態，您也可能會注意到下列症狀：

• 部分 GKE 指標未回報。
• 部分 GKE 資訊主頁和圖表有間隙。
• Pod 層級網路的連線問題。

如果發現上述任何較不明顯的症狀，下一步應確認是否發生 CrashLoopBackOff 事件。

確認CrashLoopBackOff活動

如要確認及調查 CrashLoopBackOff 事件，請從 Kubernetes 事件和容器的應用程式記錄中收集證據。這兩個來源提供不同但互補的問題檢視：

• Kubernetes 事件會確認 Pod 發生當機。
• 容器的應用程式記錄檔會顯示容器內程序失敗的原因。

如要查看這項資訊，請選取下列其中一個選項：

控制台

如要查看 Kubernetes 事件和應用程式記錄，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Workloads」(工作負載) 頁面。

   前往「Workloads」(工作負載)

2. 選取要調查的工作負載。「總覽」或「詳細資料」分頁會顯示工作負載狀態的詳細資訊。

3. 在「代管的 Pod」部分，按一下有問題的 Pod 名稱。

4. 在 Pod 詳細資料頁面中，查看下列項目：

   • 如要查看 Kubernetes 事件的詳細資料，請前往「Events」(事件)分頁。
   • 如要查看容器的應用程式記錄，請前往「Logs」(記錄) 分頁。您可以在這個頁面找到應用程式專屬的錯誤訊息或堆疊追蹤。

kubectl

如要查看 Kubernetes 事件和應用程式記錄，請按照下列步驟操作：

1. 查看叢集中所有 Pod 的執行狀態：

   kubectl get pods
   

   輸出結果會與下列內容相似：

   NAME       READY  STATUS             RESTARTS  AGE
   POD_NAME   0/1    CrashLoopBackOff   23        8d
   

   在輸出內容中，查看下列資料欄：

   • Ready：查看有多少容器已準備就緒。在本例中，0/1 表示預期有一個容器，但目前沒有任何容器處於就緒狀態。這個值明顯表示有問題。
   • Status：尋找狀態為 CrashLoopBackOff 的 Pod。
   • Restarts：如果這個值偏高，表示 Kubernetes 反覆嘗試啟動容器，但都失敗。

2. 找出失敗的 Pod 後，請說明該 Pod，查看與 Pod 狀態相關的叢集層級事件：

   kubectl describe pod POD_NAME -n NAMESPACE_NAME
   

   更改下列內容：

   • POD_NAME：您在 kubectl get 指令輸出內容中識別的 Pod 名稱。
   • NAMESPACE_NAME：Pod 的命名空間。

   輸出結果會與下列內容相似：

   Containers:
   container-name:
   ...
     State:          Waiting
       Reason:       CrashLoopBackOff
     Last State:     Terminated
       Reason:       StartError
       Message:      failed to create containerd task: failed to create shim task: context deadline exceeded: unknown
       Exit Code:    128
       Started:      Thu, 01 Jan 1970 00:00:00 +0000
       Finished:     Fri, 27 Jun 2025 16:20:03 +0000
     Ready:          False
     Restart Count:  3459
   ...
   Conditions:
   Type                        Status
   PodReadyToStartContainers   True
   Initialized                 True
   Ready                       False
   ContainersReady             False
   PodScheduled                True
   ...
   Events:
   Type     Reason   Age                     From     Message
   ----     ------   ----                    ----     -------
   Warning  Failed   12m (x216 over 25h)     kubelet  Error: context deadline exceeded
   Warning  Failed   8m34s (x216 over 25h)   kubelet  Error: context deadline exceeded
   Warning  BackOff  4m24s (x3134 over 25h)  kubelet  Back-off restarting failed container container-name in pod failing-pod(11111111-2222-3333-4444-555555555555)
   

   在輸出內容中，檢查下列欄位是否有 CrashLoopBackOff 事件的跡象：

   • State：容器的狀態可能顯示 Waiting，原因為 CrashLoopBackOff。
   • Last State：先前終止的容器狀態。尋找 Terminated 狀態，並查看結束代碼，瞭解是否發生當機 (結束代碼不為零) 或意外成功結束 (結束代碼為零)。
   • Events：叢集本身採取的動作。尋找容器啟動的訊息，接著是有效性探測失敗或類似 Back-off restarting failed container 的退避警告。

3. 如要進一步瞭解 Pod 失敗的原因，請查看應用程式記錄檔：

   kubectl logs POD_NAME --previous
   

   --previous 標記會從先前終止的容器擷取記錄，您可以在其中找到特定的堆疊追蹤或錯誤訊息，揭露當機原因。目前的容器可能太新，尚未記錄任何訊息。

   在輸出內容中，尋找會導致程序退出的應用程式特定錯誤。如果您使用自訂應用程式，撰寫該應用程式的開發人員最適合解讀這些錯誤訊息。如果您使用預先建構的應用程式，這些應用程式通常會提供自己的偵錯說明。

使用 Pod 當機循環互動式應對手冊

確認 CrashLoopBackOff 事件後，請使用互動式應對手冊開始疑難排解：

1. 前往 Google Cloud 控制台的「GKE Interactive Playbook - Crashlooping Pods」(GKE 互動式應對手冊 - Pod 的當機循環情況) 頁面。

   前往「Crashlooping Pods」(當機迴圈 Pod)

2. 在「叢集」清單中，選取要進行疑難排解的叢集。如果找不到叢集，請在「篩選」欄位中輸入叢集名稱。

3. 在「Namespace」(命名空間) 清單中，選取要排解問題的命名空間。如果找不到命名空間，請在「篩選器」欄位中輸入命名空間。

4. 請完成各個部分，協助您回答下列問題：

   1. 找出應用程式錯誤：哪些容器重新啟動？
   2. 調查記憶體不足問題：是否有設定錯誤或應用程式相關錯誤？
   3. 調查節點服務中斷情形：是否因節點資源服務中斷而讓容器重新啟動？
   4. 調查有效性探測失敗問題：有效性探測是否會停止容器？
   5. 找出變更事件的關聯性：容器停止運作前發生了什麼事？

5. 選用步驟：如要接收日後 CrashLoopBackOff 事件的通知，請在「Future Mitigation Tips」(日後緩解措施提示) 部分中，選取「Create an Alert」(建立快訊)。

如果使用劇本後問題仍未解決，請參閱本指南的其餘部分，進一步瞭解如何解決 CrashLoopBackOff 事件。

解決 CrashLoopBackOff 事件

以下各節有助於解決 CrashLoopBackOff 事件最常見的原因：

• 資源耗盡 (OOMKilled)
• 有效性探測失敗
• 設定錯誤的應用程式

解決資源耗盡問題

CrashLoopBackOff 事件通常是由記憶體不足 (OOM) 問題所導致。如果 kubectl describe 輸出內容顯示下列項目，即可確認是否為這個原因：

Last State: Terminated
  Reason: OOMKilled

如要瞭解如何診斷及解決 OOM 事件，請參閱「排解 OOM 事件」。

解決有效性探測失敗問題

運作狀態探測是 kubelet 執行的定期健康狀態檢查。如果探測失敗次數達到指定次數 (預設為三次)，kubelet 會重新啟動容器，如果探測持續失敗，可能會導致 CrashLoopBackOff 事件。

確認 liveness 探測是否為原因

如要確認有效性探測失敗是否觸發 CrashLoopBackOff 事件，請查詢 kubelet 記錄。這些記錄通常包含明確的訊息，指出探測失敗和後續重新啟動。

1. 前往 Google Cloud 控制台的「Logs Explorer」頁面。

   前往 Logs Explorer

2. 在查詢窗格中，輸入下列查詢，篩選出與存活探查相關的任何重新啟動：

   resource.type="k8s_node"
   log_id("kubelet")
   jsonPayload.MESSAGE:"failed liveness probe, will be restarted"
   resource.labels.cluster_name="CLUSTER_NAME"
   

   將 CLUSTER_NAME 替換為叢集名稱。

3. 查看輸出內容。如果有效性探測失敗是 CrashLoopBackOff 事件的原因，查詢會傳回類似下列內容的記錄訊息：

   Container probe failed liveness probe, will be restarted
   

確認是存活探查導致CrashLoopBackOff事件後，請繼續排解常見原因：

• 檢查有效性探測設定。
• 檢查 CPU 和磁碟 I/O 使用率。
• 處理大規模部署作業。
• 解決暫時性錯誤。
• 解決探查資源耗用問題。

檢查有效性探測設定

探針設定錯誤是 CrashLoopBackOff 事件的常見原因。請檢查探測資訊清單中的下列設定：

• 驗證探測類型：探測設定必須與應用程式回報健康狀態的方式相符。舉例來說，如果應用程式有健康狀態檢查網址 (例如 /healthz)，請使用 httpGet 探測類型。如果健康狀態是透過執行指令來判斷，請使用 exec 探測類型。舉例來說，如要檢查網路通訊埠是否開啟並監聽，請使用 tcpSocket 探測類型。
• 檢查探測參數：
  • 路徑 (適用於 httpGet 探測類型)：確認 HTTP 路徑正確無誤，且應用程式會對該路徑執行健康狀態檢查。
  • 通訊埠：確認探測器中設定的通訊埠是否確實由應用程式使用及公開。
  • 指令 (適用於 exec 探測類型)：請確認指令位於容器中，成功時會傳回 0 的結束代碼，並在設定的 timeoutSeconds 期間內完成。
  • 逾時：請確認 timeoutSeconds 值是否足夠讓應用程式回應，尤其是在啟動或負載期間。
  • 初始延遲 (initialDelaySeconds)：檢查初始延遲是否足以讓應用程式在探查開始前啟動。

詳情請參閱 Kubernetes 說明文件的「設定有效性、完備性和啟動探測功能」。

檢查 CPU 和磁碟 I/O 使用率

資源爭用會導致探測逾時，這是造成存活探測失敗的主要原因。如要確認資源用量是否導致存活探查失敗，請嘗試下列解決方案：

• 分析 CPU 使用率：在探測間隔期間，監控受影響容器和執行該容器的節點的 CPU 使用率。kubernetes.io/container/cpu/core_usage_time 是需要追蹤的重要指標。如果容器或節點的 CPU 使用率偏高，應用程式可能無法及時回應探測。

  如果容器 CPU 資源不足，導致初始化期間探測失敗，您可以使用 CPU 啟動提升功能，暫時分配更多 CPU 資源。詳情請參閱「使用 CPU 啟動加速功能加快應用程式啟動速度」。

• 監控磁碟 I/O：檢查節點的磁碟 I/O 指標。您可以運用 compute.googleapis.com/guest/disk/operation_time 指標評估磁碟作業耗費的時間，並依讀取和寫入作業分類。磁碟 I/O 偏高可能會大幅降低容器啟動速度、應用程式初始化速度或整體應用程式效能，導致探查逾時。

處理大規模部署作業

如果同時部署大量 Pod (例如透過 ArgoCD 等 CI/CD 工具)，新 Pod 突然大量湧入可能會導致叢集資源不堪負荷，進而耗盡控制層資源。資源不足會延遲應用程式啟動，並可能導致有效性探測在應用程式準備就緒前反覆失敗。

如要解決這個問題，請嘗試下列解決方法：

• 實施分階段部署：採取分批或分時段部署 Pod 的策略，避免節點資源不堪負荷。
• 重新設定或擴充節點：如果無法交錯部署，請考慮使用速度更快或容量更大的磁碟，或使用永久磁碟聲明升級節點，以便更妥善地處理增加的 I/O 需求。確認叢集自動調度設定正確無誤。
• 等待並觀察：在某些情況下，如果叢集資源不足的情況不嚴重，工作負載可能會在明顯延遲後 (有時 30 分鐘以上) 部署。

解決暫時性地址錯誤

應用程式在啟動或初始化期間，可能會發生暫時性錯誤或速度變慢，導致探測一開始失敗。如果應用程式最終復原，請考慮增加存活度探測資訊清單中 initialDelaySeconds 或 failureThreshold 欄位定義的值。

處理探測資源消耗

在極少數情況下，執行存活狀態探測本身可能會耗用大量資源，進而觸發資源限制，導致容器因 OOM 終止而終止。請確保探查指令輕量化。輕量型探針的執行速度和可靠性較高，因此能更準確地回報應用程式的實際健康狀態。

解決應用程式設定錯誤的問題

應用程式設定錯誤會導致許多 CrashLoopBackOff 事件。如要瞭解應用程式停止的原因，請先檢查其結束代碼。這個代碼會決定疑難排解路徑：

• 結束代碼 0 表示成功結束，但對於長時間執行的服務來說，這是不正常的現象，代表容器的進入點或應用程式設計有問題。
• 非零的結束代碼表示應用程式當機，因此您應著重於設定錯誤、依附元件問題或程式碼中的錯誤。

尋找退出代碼

如要找出應用程式的結束代碼，請按照下列步驟操作：

1. 描述 Pod：

   kubectl describe pod POD_NAME -n NAMESPACE_NAME
   

   更改下列內容：

   • POD_NAME：有問題的 Pod 名稱。
   • NAMESPACE_NAME：Pod 的命名空間。

2. 在輸出內容中，查看相關容器的 Last State 區段下方的 Exit Code 欄位。如果結束代碼為 0，請參閱「排解成功結束的問題 (結束代碼 0)」。如果結束代碼不是 0，請參閱「排解應用程式當機問題 (非零結束代碼)」。

疑難排解成功結束的問題 (結束代碼 0)

結束代碼 0 通常表示容器的程序已順利完成。雖然這是以工作為基礎的 Job 所需的結果，但對於 Deployment、StatefulSet 或 ReplicaSet 等長時間執行的控制器而言，這可能代表有問題。

這些控制器會確保 Pod 一律處於執行狀態，因此會將任何結束視為失敗並加以修正。kubelet 會遵守 Pod 的 restartPolicy (預設為 Always)，即使容器成功結束，也會重新啟動，藉此強制執行這項行為。這項動作會建立迴圈，最終觸發 CrashLoopBackOff 狀態。

非預期成功結束的最常見原因如下：

• 容器指令不會啟動永久程序：容器只有在初始程序 (command 或 entrypoint) 執行時才會繼續執行。如果這項程序不是長時間執行的服務，容器會在指令完成後立即結束。舉例來說，["/bin/bash"] 這類指令會立即結束，因為沒有要執行的指令碼。如要解決這個問題，請確保容器的初始程序會啟動持續執行的程序。

• 工作佇列為空時，Worker 應用程式會結束：許多 Worker 應用程式的設計都是檢查佇列中的工作，如果佇列為空，就會乾淨利落地結束。如要解決這個問題，您可以使用工作控制器 (專為執行至完成的工作設計)，或修改應用程式邏輯，讓應用程式以永久服務的形式執行。

• 應用程式因缺少或無效的設定而結束：如果缺少必要的啟動指令 (例如指令列引數、環境變數或重要設定檔)，應用程式可能會立即結束。

  如要解決這個問題，請先檢查應用程式記錄檔，找出與設定載入或缺少參數相關的特定錯誤訊息。然後，驗證下列事項：

  • 應用程式引數或環境：確認所有必要的指令列引數和環境變數都已正確傳遞至容器，符合應用程式的預期。
  • 設定檔是否存在：確認所有必要設定檔都位於容器內的預期路徑。
  • 設定檔內容：驗證設定檔的內容和格式，檢查是否有語法錯誤、缺少必要欄位或值不正確。

  這類問題的常見例子是，應用程式設為從使用 ConfigMap 磁碟區掛接的檔案讀取資料。如果 ConfigMap 未附加、空白或金鑰名稱有誤，應用程式可能會在缺少設定時停止運作，並顯示 0 的結束代碼。在這種情況下，請驗證下列設定： - Pod 磁碟區定義中的 ConfigMap 名稱與實際名稱相符。- ConfigMap 中的金鑰與應用程式預期在掛接磁碟區中找到的檔案名稱相符。

  注意： 雖然設計良好的應用程式在缺少必要設定時，應以非零錯誤代碼結束，但有些應用程式在這種情況下會以代碼 0 成功結束。

排解應用程式當機問題 (非零退出代碼)

如果容器以非零代碼結束，Kubernetes 會重新啟動容器。如果導致錯誤的根本問題持續存在，應用程式會再次當機，然後重複這個週期，最終進入 CrashLoopBackOff 狀態。

非零的結束代碼清楚指出應用程式本身發生錯誤，因此您應將偵錯工作導向應用程式的內部運作和環境。以下是導致終止的常見問題：

• 設定錯誤：非零的結束代碼通常表示應用程式的設定或執行環境有問題。檢查應用程式是否有下列常見問題：

  • 缺少設定檔：應用程式可能無法找到或存取必要的設定檔。
  • 設定無效：設定檔可能含有語法錯誤、不正確的值或不相容的設定，導致應用程式當機。
  • 權限問題：應用程式可能缺少讀取或寫入設定檔的必要權限。
  • 環境變數：環境變數有誤或缺漏可能會導致應用程式故障或無法啟動。
  • 無效的 entrypoint 或 command：容器的 entrypoint 或 command 欄位中指定的指令可能不正確。如果新部署的映像檔中，可執行檔的路徑有誤，或容器映像檔中沒有檔案本身，就可能發生這個問題。這類設定錯誤通常會導致 128 結束代碼。

  • 不受控的映像檔更新 (:latest 標記)：如果工作負載映像檔使用 :latest 標記，新的 Pod 可能會提取更新的映像檔版本，進而造成重大變更。

    為確保一致性和可重現性，請務必在正式環境中使用特定、不可變更的映像檔標記 (例如 v1.2.3) 或 SHA 摘要 (例如 sha256:45b23dee08...)。這麼做可確保每次都提取完全相同的圖片內容。

• 依附元件問題：如果應用程式無法連線至依附的其他服務、無法驗證或沒有足夠的存取權限，就可能發生當機。

  • 外部服務無法使用：應用程式可能依賴外部服務 (例如資料庫或 API)，但因網路連線問題或服務中斷而無法連線。如要排解這個問題，請連線至 Pod。詳情請參閱 Kubernetes 說明文件中的「對執行中的 Pod 進行偵錯」。

    連線至 Pod 後，您可以執行指令來檢查檔案或資料庫的存取權，或是測試網路。舉例來說，您可以使用 curl 等工具嘗試連線至服務的網址。這項操作有助於判斷問題是否是由網路政策、DNS 或服務本身所致。

  • 驗證失敗：應用程式可能因憑證不正確，而無法向外部服務驗證。檢查容器的記錄檔，尋找 401 Unauthorized (憑證無效) 或 403 Forbidden (權限不足) 等訊息，這通常表示 Pod 的服務帳戶缺少進行外部服務呼叫所需的 IAM 角色。 Google Cloud

    如果您使用 GKE Workload Identity Federation，請確認主體 ID 具備工作所需的權限。如要進一步瞭解如何使用 GKE Workload Identity Federation，將 IAM 角色授予主體，請參閱「設定授權和主體」。此外，請務必確認 GKE 中繼資料伺服器的資源用量未超過限制。

  • 逾時：應用程式在等待外部服務回應時可能會逾時，導致當機。

• 應用程式專屬錯誤：如果設定和外部依附元件似乎正確無誤，錯誤可能出現在應用程式的程式碼中。請檢查應用程式記錄，找出下列常見的內部錯誤：

  • 未處理的例外狀況：應用程式記錄可能包含堆疊追蹤記錄或錯誤訊息，指出未處理的例外狀況或其他與程式碼相關的錯誤。
  • 死結或活結：應用程式可能卡在死結中，多個程序互相等待對方完成。在這種情況下，應用程式可能不會結束，但會無限期停止回應。
  • 通訊埠衝突：如果應用程式嘗試繫結至其他程序已使用的通訊埠，可能無法啟動。
  • 不相容的程式庫：應用程式可能依附於遺失或與執行階段環境不相容的程式庫或依附元件。

  如要找出根本原因，請檢查容器記錄中的特定錯誤訊息或堆疊追蹤。這項資訊可協助您決定是否要修正應用程式程式碼、調整資源限制，或修正環境的設定。如要進一步瞭解記錄，請參閱「關於 GKE 記錄」。

後續步驟

• 如果無法在文件中找到問題的解決方案，請參閱「取得支援」一文，取得進一步協助，包括下列主題的建議：

  • 向 Cloud Customer Care 團隊申請開立支援案件。
  • 在 StackOverflow 上提問，並使用 google-kubernetes-engine 標記搜尋類似問題，向社群尋求支援。您也可以加入 #kubernetes-engine Slack 頻道，取得更多社群支援。
  • 使用公開 Issue Tracker 開啟問題或功能要求。