排解 GKE 中缺少記錄的問題

自動駕駛 標準

如果 Google Kubernetes Engine (GKE) 的記錄管道發生問題，叢集記錄檔可能無法顯示在 Cloud Logging 中，進而影響監控和偵錯作業。

請參閱這份文件，瞭解如何驗證設定和權限、解決資源和效能問題、調查篩選器和應用程式行為，以及解決影響記錄的平台或服務問題。

這項資訊對平台管理員和運算子來說非常重要，因為他們負責維護叢集觀測能力，而且任何使用 Cloud Logging 排解 GKE 作業問題的人，也都需要這項資訊。如要進一步瞭解我們在 Google Cloud 內容中提及的常見角色和範例工作，請參閱「常見的 GKE 使用者角色和工作」。

如要進一步瞭解如何使用記錄檔排解工作負載和叢集問題，請參閱「使用 Cloud Logging 進行歷來分析」。

依症狀尋找解決方案

如果發現特定症狀與記錄檔遺失有關，請參閱下表中的疑難排解建議：

類別	症狀或觀察結果	可能原因	疑難排解步驟
設定	您無法查看專案中任何叢集的記錄。	專案已停用 Cloud Logging API。	確認 Cloud Logging API 狀態
	特定叢集缺少記錄，或只有特定記錄類型缺少記錄。	必要記錄類型已停用叢集層級記錄功能。	驗證叢集記錄設定
	特定節點集區中的節點缺少記錄。	節點集區的節點缺少必要存取權範圍。	驗證節點集區存取權範圍
	記錄代理程式記錄中會顯示權限錯誤 (401 或 403)。	節點的服務帳戶缺少必要權限。	驗證節點服務帳戶權限
資源和成效	記錄間歇性遺失，或您看到 RESOURCE_EXHAUSTED 錯誤。	專案超過 Cloud Logging API 寫入配額。	調查 Cloud Logging API 配額用量
	特定節點的部分記錄遺失，通常發生在高流量或高負載期間。	節點超出記錄代理程式的輸送量限制，或缺少處理記錄的資源 (CPU 或記憶體)。	調查節點輸送量和資源用量
篩選和應用程式行為	符合特定模式的特定記錄持續遺失。	Cloud Logging 中的記錄排除篩選器意外捨棄記錄。	調查記錄排除篩選器
	容器的記錄大幅延遲，或只會在容器結束後顯示。	應用程式的輸出內容已完全緩衝，通常是因為管道 stdout 所致。	調查容器記錄緩衝和延遲問題
	搜尋結果未顯示預期記錄。	Logs Explorer 中的查詢篩選器可能過於嚴格。	調查記錄檔探索工具查詢
	特定應用程式 Pod 中沒有記錄，但其他叢集記錄存在。	容器內的應用程式未寫入 stdout 或 stderr。	調查應用程式專屬的記錄行為
平台和服務	系統不會顯示特定日期之前的記錄。	記錄檔已超過保留期限，並由 Cloud Logging 刪除。	調查記錄保留期限
	專案或叢集發生大規模記錄檔遺失或延遲。	Cloud Logging 服務發生問題或擷取作業延遲。	調查 Cloud Logging 服務問題和延遲情形
	記錄問題與叢集版本限制有關。	不支援的 GKE 版本。	調查叢集版本

使用自動診斷工具

以下各節將介紹可自動檢查叢集常見設定錯誤的工具，並協助您調查複雜問題。

使用 gcpdiag 偵錯 GKE 記錄問題

如果 GKE 叢集缺少記錄或記錄不完整，請使用 gcpdiag 工具進行疑難排解。

gcpdiag 是開放原始碼工具。這並非正式支援的 Google Cloud 產品。您可以使用 gcpdiag 工具找出並修正專案問題。 Google Cloud詳情請參閱 GitHub 上的 gcpdiag 專案。

如果 GKE 叢集的記錄遺失或不完整，請著重於下列核心設定，調查可能原因：

• 專案層級記錄：確保裝載 GKE 叢集的專案已啟用 Cloud Logging API。 Google Cloud
• 叢集層級記錄：確認 GKE 叢集設定中已明確啟用記錄功能。
• 節點集區權限：確認叢集節點集區中的節點已啟用 Cloud Logging Write 範圍，可傳送記錄資料。
• 服務帳戶權限：驗證節點集區使用的服務帳戶是否具備與 Cloud Logging 互動所需的 IAM 權限。具體來說，通常需要 roles/logging.logWriter 角色。
• Cloud Logging API 寫入配額：確認在指定時間範圍內，Cloud Logging API 寫入配額未超出上限。

Google Cloud 控制台

1. 完成下列指令，然後複製。

gcpdiag runbook gke/logs \
    --parameter project_id=PROJECT_ID \
    --parameter name=CLUSTER_NAME \
    --parameter location=LOCATION

2. 開啟 Google Cloud 控制台並啟用 Cloud Shell。
開啟 Cloud 控制台
3. 貼上複製的指令。
4. 執行 gcpdiag 指令，下載 gcpdiag Docker 映像檔，然後執行診斷檢查。如果適用，請按照輸出內容中的操作說明修正失敗的檢查。

Docker

您可以使用在 Docker 容器中啟動 gcpdiag 的 wrapper 執行 gcpdiag。必須安裝 Docker 或 Podman。

1. 在本機工作站上複製並執行下列指令。

   curl https://gcpdiag.dev/gcpdiag.sh >gcpdiag && chmod +x gcpdiag

2. 執行 gcpdiag 指令。

   ./gcpdiag runbook gke/logs \
       --parameter project_id=PROJECT_ID \
       --parameter name=CLUSTER_NAME \
       --parameter location=LOCATION

查看這本 Runbook 的可用參數。

更改下列內容：

• PROJECT_ID：包含資源的專案 ID。
• CLUSTER_NAME：GKE 叢集的名稱。
• LOCATION：叢集的 Compute Engine 區域或可用區 (例如 us-central1 或 us-central1-a)。

實用旗標：

• --universe-domain：如果適用，則為代管資源的信任合作夥伴主權雲端網域
• --parameter 或 -p：Runbook 參數

如需所有 gcpdiag 工具標記的清單和說明，請參閱 gcpdiag 使用說明。

使用 Gemini Cloud Assist 調查

建議使用 Gemini Cloud Assist 調查，進一步瞭解記錄檔並解決問題。如要進一步瞭解如何使用 Logs Explorer 啟動調查，請參閱 Gemini 說明文件中的「排解 Gemini Cloud Assist Investigations 的問題」。

確認記錄設定和權限

設定不正確是缺少 GKE 記錄的常見原因。請參閱下列各節，確認 Cloud Logging 設定。

確認 Cloud Logging API 狀態

如要從專案中的任何叢集收集記錄，必須啟用 Cloud Logging API。

症狀：

Cloud Logging 中不會顯示專案中任何 GKE 資源的記錄。

原因：

Google Cloud 專案已停用 Cloud Logging API，導致節點上的記錄代理程式無法傳送記錄。

解決方法：

如要確認 Cloud Logging API 是否已啟用，並視需要啟用，請選取下列其中一個選項：

控制台

1. 在 Google Cloud 控制台中，前往「已啟用的 API 和服務」頁面。

   前往「已啟用的 API 和服務」頁面

2. 在「Filter」欄位中輸入 Cloud Logging API，然後按 Enter 鍵。

3. 如果 API 已啟用，您會看到該 API 列在清單中。如果選單未列出您需要的 API，請啟用該 API：

   1. 按一下「啟用 API 和服務」。
   2. 在「搜尋」欄位中輸入 Cloud Logging API，然後按 Enter 鍵。
   3. 點選「Cloud Logging API」結果。
   4. 按一下「啟用」。

gcloud

1. 檢查 API 是否已啟用：

   gcloud services list --enabled --filter="NAME=logging.googleapis.com"
   

   輸出內容應如下所示：

   NAME: logging.googleapis.com
   TITLE: Cloud Logging API
   

2. 如果 API 未列在已啟用的服務中，請啟用該 API：

   gcloud services enable logging.googleapis.com \
       --project=PROJECT_ID
   

   將 PROJECT_ID 替換為專案 ID。 Google Cloud

驗證叢集記錄設定

您可以透過 GKE 設定要從叢集收集哪些記錄類型 (例如 SYSTEM 或 WORKLOAD)。

症狀：

Cloud Logging 未顯示特定 GKE 叢集的記錄，或只缺少特定類型的記錄 (例如 SYSTEM)。

原因：

必要記錄類型已停用叢集層級記錄功能。如果您使用的是 Autopilot 叢集，這就不是記錄問題的原因。這項設定適用於 Standard 叢集，但 Autopilot 叢集預設一律會啟用這項設定，且無法停用。

解決方法：

如要檢查及更新叢集的記錄設定，請選取下列其中一個選項：

控制台

1. 在 Google Cloud 控制台中，前往「Kubernetes clusters」(Kubernetes 叢集) 頁面。

   前往 Kubernetes 叢集

2. 按一下要調查的叢集名稱。

3. 按一下「詳細資料」分頁標籤，然後前往「功能」部分。

4. 在「記錄」列中，查看已啟用的記錄類型，例如「系統」或「工作負載」。

5. 如果想收集的記錄類型已停用或不正確，請按一下「編輯記錄」。

6. 在「Components」(元件) 清單中，選取要收集的記錄類型核取方塊，然後按一下「OK」(確定)。如要進一步瞭解可用的記錄類型，請參閱「關於 GKE 記錄」。

7. 按一下 [儲存變更]。

gcloud

1. 如要檢查記錄設定，請說明叢集：

   gcloud container clusters describe CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --format="value(name,loggingConfig.componentConfig.enableComponents)"
   

   更改下列內容：

   • CLUSTER_NAME：叢集名稱。
   • LOCATION：叢集的 Compute Engine 區域或可用區 (例如 us-central1 或 us-central1-a)。
   • PROJECT_ID：您的 Google Cloud 專案 ID。

   如果記錄功能已啟用，輸出結果會與下列內容相似：

   example-cluster    SYSTEM_COMPONENTS;WORKLOADS
   

   如果輸出結果是 NONE，表示記錄功能已停用。

2. 如果想使用的記錄類型已停用或不正確，請更新記錄設定：

   gcloud container clusters update CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --logging=LOGGING_TYPE
   

   將 LOGGING_TYPE 替換為 SYSTEM、WORKLOAD 或兩者。如要收集任何記錄，請務必啟用 SYSTEM。 WORKLOAD 無法自行收集記錄。如要進一步瞭解可用的記錄類型，請參閱「關於 GKE 記錄」。

驗證節點集區存取權範圍

GKE 叢集中的節點會使用 OAuth 存取範圍，取得與 Google Cloud API (包括 Cloud Logging) 互動的權限。

症狀：

特定節點集區中的節點缺少記錄。

原因：

節點集區中的節點沒有必要的 OAuth 存取範圍。節點必須具備下列其中一個範圍，才能將記錄寫入 Cloud Logging：

• https://www.googleapis.com/auth/logging.write：授予寫入記錄的權限。這是最低必要範圍。
• https://www.googleapis.com/auth/logging.admin：授予 Cloud Logging API 的完整存取權，包括 logging.write 的權限。
• https://www.googleapis.com/auth/cloud-platform：授予所有已啟用 API 的完整存取權，包括 logging.write 的權限。 Google Cloud

解決方法：

如要驗證權限，並在缺少必要角色時授予權限，請選取下列其中一個選項：

控制台

1. 驗證節點集區的存取範圍：

   1. 在 Google Cloud 控制台中，前往「Kubernetes clusters」(Kubernetes 叢集) 頁面。

      前往 Kubernetes 叢集

   2. 如要開啟叢集的詳細資料頁面，請按一下要調查的叢集名稱。

   3. 按一下「Nodes」(節點) 分頁標籤。

   4. 在「Node Pools」(節點集區) 區段中，按一下要調查的節點集區名稱。

   5. 前往「安全性」部分。

   6. 查看「存取權範圍」欄位中列出的範圍。確認至少存在一個必要範圍：

      • Stackdriver Logging API - Write Only
      • Stackdriver Logging API - Full
      • Cloud Platform - Enabled

      如果缺少必要範圍，請重新建立節點集區。您無法變更現有節點集區的存取權範圍。

2. 視需要建立具有必要範圍的新節點集區：

   1. 返回要修改的叢集詳細資料頁面。
   2. 按一下「Nodes」(節點) 分頁標籤。
   3. 按一下 「建立由使用者管理的節點集區」。
   4. 填寫「節點集區詳細資料」部分。
   5. 按一下左側導覽區中的「安全性」。
   6. 在「存取範圍」部分，選取要新增的角色：
      • 如要新增特定範圍，請選取「針對各個 API 設定存取權」。
      • 如要允許完整存取權，請選取「允許所有 Cloud API 的完整存取權」。
   7. 視需要設定其他部分。
   8. 點選「建立」。

3. 將工作負載遷移至新的節點集區。將工作負載遷移至新節點集區後，應用程式會在具備必要範圍的節點上執行，以便將記錄傳送至 Cloud Logging。

4. 刪除舊的節點集區：

   1. 返回叢集詳細資料頁面，然後選取「節點」分頁標籤。
   2. 在「Node Pools」(節點集區) 區段中，找到舊節點集區。
   3. 按一下節點集區旁邊的 「刪除」。
   4. 系統提示時，請輸入節點集區名稱，然後按一下「Delete」(刪除)，確認刪除。

gcloud

1. 驗證節點集區的存取範圍：

   gcloud container clusters describe CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --format="value(nodePools[].name,nodePools[].config.oauthScopes)"
   

   更改下列內容：

   • CLUSTER_NAME：叢集名稱。
   • LOCATION：叢集的 Compute Engine 區域或可用區 (例如 us-central1 或 us-central1-a)。
   • PROJECT_ID：您的 Google Cloud 專案 ID。

   查看每個節點集區的輸出內容。確認列出至少一個必要範圍 (https://www.googleapis.com/auth/logging.write、https://www.googleapis.com/auth/cloud-platform 或 https://www.googleapis.com/auth/logging.admin)。如果缺少必要範圍，請重新建立節點集區。您無法變更現有節點集區的存取範圍。

2. 視需要建立具有必要範圍的新節點集區：

   gcloud container node-pools create NEW_NODE_POOL_NAME \
       --cluster=CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --scopes=https://www.googleapis.com/auth/logging.write,OTHER_SCOPES
   

   更改下列內容：

   • NEW_NODE_POOL_NAME：新節點集區的名稱。
   • OTHER_SCOPES：以半形逗號分隔的清單，列出節點所需的任何其他範圍。如果不需要其他範圍，請省略這個預留位置和前面的半形逗號。

3. 將工作負載遷移至新的節點集區。將工作負載遷移至新節點集區後，應用程式會在具備必要範圍的節點上執行，以便將記錄傳送至 Cloud Logging。

4. 刪除舊的節點集區：

   gcloud container node-pools delete OLD_NODE_POOL_NAME \
       --cluster=CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID
   

驗證節點服務帳戶權限

節點會使用服務帳戶向服務進行驗證，而這個帳戶需要特定的 IAM 權限才能寫入記錄。 Google Cloud

症狀：

• 節點缺少記錄。
• 檢查記錄代理程式記錄 (例如 Fluent Bit) 時，可能會顯示權限相關錯誤，例如嘗試寫入 Cloud Logging 時出現 401 或 403 代碼。
• 您可能會在 Google Cloud 控制台中看到叢集的Grant Critical Permissions to Node Service Account通知。

原因：

節點集區節點使用的服務帳戶缺少必要的 IAM 權限，無法將記錄寫入 Cloud Logging。節點需要具備 logging.logWriter 角色的服務帳戶，該角色包含 logging.logEntries.create 權限。

此外，如果是 GKE 1.33 以上版本，GKE 預設節點服務代理程式 ([e-mail]) 至少須具備 Kubernetes 預設節點服務代理程式 (roles/container.defaultNodeServiceAgent) 角色。這個角色可讓 GKE 管理節點資源和作業，包括記錄元件。

解決方法：

如要驗證權限並授予必要角色 (如有遺漏)，請按照下列步驟操作：

• 確認節點的服務帳戶權限。
• 確認 GKE 服務代理具備必要角色。

驗證節點服務帳戶權限

節點服務帳戶是節點用來驗證及傳送記錄的帳戶。如要找出這個服務帳戶並確認其具備必要的 roles/logging.logWriter 權限，請按照下列步驟操作：

1. 如要找出節點集區使用的服務帳戶，請選取下列其中一個選項：

   控制台

   1. 在 Google Cloud 控制台中，前往「Kubernetes clusters」(Kubernetes 叢集) 頁面。

      前往 Kubernetes 叢集

   2. 在叢集清單中，按一下要檢查的叢集名稱。

   3. 視叢集運作模式而定，請執行下列其中一項操作：

      • 如果是 Standard 叢集，請執行下列操作：

        1. 按一下「Nodes」(節點) 分頁標籤。
        2. 在「節點集區」表格中，按一下節點集區名稱。節點集區詳細資料頁面隨即開啟。
        3. 在「安全性」部分，找到「服務帳戶」欄位。

      • 如果是 Autopilot 叢集，請執行下列操作：

        1. 前往「詳細資料」分頁。
        2. 在「安全性」部分，找到「服務帳戶」欄位。

      如果「服務帳戶」欄位中的值為 default，節點會使用 Compute Engine 預設服務帳戶。如果這個欄位的值不是 default，節點就會使用自訂服務帳戶。如要將必要角色授予自訂服務帳戶，請參閱「使用最低權限的 IAM 服務帳戶」。

   gcloud

   根據您使用的叢集類型，執行下列指令：

   標準叢集

   gcloud container node-pools describe NODE_POOL_NAME \
       --cluster=CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --format="value(config.serviceAccount)"
   

   更改下列內容：

   • NODE_POOL_NAME：節點集區的名稱。
   • CLUSTER_NAME：標準叢集的名稱。
   • LOCATION：叢集的 Compute Engine 區域或可用區 (例如 us-central1 或 us-central1-a)。
   • PROJECT_ID：您的 Google Cloud專案 ID。

   如果輸出為 default，則節點集區會使用 Compute Engine 預設服務帳戶。如果值不是 default，節點會使用自訂服務帳戶。如要將必要角色授予自訂服務帳戶，請參閱「使用最小權限的 IAM 服務帳戶」。

   Autopilot 叢集

   gcloud container clusters describe CLUSTER_NAME \
       --location=LOCATION \
       --project=PROJECT_ID \
       --format="value(nodePoolDefaults.nodeConfigDefaults.serviceAccount)"
   

   更改下列內容：

   • CLUSTER_NAME：Autopilot 叢集名稱。
   • LOCATION：叢集的 Compute Engine 區域或可用區 (例如 us-central1 或 us-central1-a)。
   • PROJECT_ID：您的 Google Cloud 專案 ID。

   如果輸出為 default，則節點集區會使用 Compute Engine 預設服務帳戶。如果值不是 default，節點會使用自訂服務帳戶。如要將必要角色授予自訂服務帳戶，請參閱「使用最小權限的 IAM 服務帳戶」。

   如需更詳細的指令碼來找出缺少的權限，請參閱「找出所有缺少權限的節點服務帳戶」。

2. GKE 會自動掃描缺少的權限，並提供建議。如要使用最佳化建議檢查缺少的權限，請選取下列其中一個選項：

   控制台

   1. 在「Kubernetes clusters」(Kubernetes 叢集) 頁面中，找到「Notifications」(通知) 欄。
   2. 查看「通知」欄，找出「授予重要權限」建議。這項建議表示 NODE_SA_MISSING_PERMISSIONS 檢查失敗。
   3. 如果系統提供建議，請按一下。系統會開啟詳細資料面板，說明缺少哪些權限，並提供修正步驟。

   gcloud

   1. 列出缺少服務帳戶權限的建議：

      gcloud recommender recommendations list \
          --recommender=google.container.DiagnosisRecommender \
          --location LOCATION \
          --project PROJECT_ID \
          --format yaml \
          --filter="recommenderSubtype:NODE_SA_MISSING_PERMISSIONS"
      

   2. 分析指令輸出內容：

      • 如果指令傳回空白清單，表示推薦工具未找到任何有效的 NODE_SA_MISSING_PERMISSIONS 建議。檢查的服務帳戶似乎具備必要權限。

      • 如果指令傳回一或多個 YAML 區塊，表示建議引擎已找出權限問題。請檢查下列重要欄位的輸出內容：

        • description：提供問題摘要，例如指定節點服務帳戶缺少 roles/logging.logWriter 角色，或 GKE 服務代理程式缺少 roles/container.defaultNodeServiceAgent 角色。
        • resource：指定受影響的叢集。
        • content.operations：包含建議的解析度。 這個專區會提供確切的 gcloud projects add-iam-policy-binding 指令，用來授予缺少的特定角色。

   建議最多可能需要 24 小時才會反映近期變更。

3. 如要立即驗證權限，請選取下列其中一個選項，檢查權限並授予角色：

   控制台

   1. 前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。

      前往「IAM」頁面

   2. 找出節點集區使用的服務帳戶。

   3. 在「角色」欄中，檢查服務帳戶是否具備「記錄檔寫入者」 (roles/logging.logWriter) 角色。

   4. 如果缺少權限，請新增權限：

      1. 按一下「編輯主體」
      2. 按一下 「Add another role」(新增其他角色)。
      3. 在搜尋欄位中輸入 Logs Writer。
      4. 勾選「記錄寫入器」核取方塊，然後按一下「套用」。
      5. 按一下 [儲存]。

   gcloud

   1. 檢查節點服務帳戶的目前角色：

      gcloud projects get-iam-policy PROJECT_ID \
          --flatten="bindings[].members" \
          --format='table(bindings.role)' \
          --filter="bindings.members:serviceAccount:SERVICE_ACCOUNT_EMAIL"
      

   2. 如果沒有，請授予 logging.logWriter 角色：

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
          --role="roles/logging.logWriter"
      

驗證 GKE 服務代理權限

如果記錄檔仍未顯示，且您使用的是 1.33 以上版本，請確認 GKE 用於管理節點元件的 Google 管理代理程式是否具備必要權限：

1. 如要找出服務專員的電子郵件地址，請取得專案編號：

   gcloud projects describe PROJECT_ID --format="value(projectNumber)"
   

   並將 PROJECT_ID 替換為專案 ID。請注意輸出內容。

   GKE 服務代理的電子郵件地址為： [e-mail]

2. 如要使用最佳化建議檢查缺少的權限，請選取下列其中一個選項：

   控制台

   1. 在「Kubernetes clusters」(Kubernetes 叢集) 頁面中，找到「Notifications」(通知) 欄。
   2. 查看「授予重要權限」建議的資料欄。
   3. 如果系統提供建議，請按一下。系統會開啟詳細資料面板，說明缺少哪些權限，並提供修正步驟。

   gcloud

   1. 列出缺少服務帳戶權限的建議：

      gcloud recommender recommendations list \
          --recommender=google.container.DiagnosisRecommender \
          --location LOCATION \
          --project PROJECT_ID \
          --format yaml \
          --filter="recommenderSubtype:NODE_SA_MISSING_PERMISSIONS"
      

   2. 分析指令輸出內容。查看輸出內容，確認說明是否指出 GKE 服務代理程式 (gcp-sa-gkenode) 缺少 roles/container.defaultNodeServiceAgent 角色。

3. 如要立即檢查權限並授予角色，請選取下列其中一個選項：

   控制台

   1. 前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。

      前往「IAM」頁面

   2. 在「Filter」(篩選器) 欄位中，輸入 GKE 服務代理程式的電子郵件地址，然後按下 Enter 鍵。

   3. 在篩選後的清單中，檢查服務代理程式是否至少具備 Kubernetes 預設節點服務代理程式 (roles/container.defaultNodeServiceAgent) 角色。

   4. 如果缺少角色，請授予角色：

      1. 按一下服務代理程式旁的「編輯主體」。
      2. 按一下 「新增角色」。
      3. 在搜尋欄位中輸入 Kubernetes Default Node Service Agent，然後選取角色。
      4. 按一下 [儲存]。

   gcloud

   1. 確認 roles/container.defaultNodeServiceAgent 角色是否繫結至服務代理程式：

      gcloud projects get-iam-policy PROJECT_ID \
          --flatten="bindings[].members" \
          --format='table(bindings.role)' \
          --filter="bindings.members:serviceAccount:[e-mail]"
      

      在輸出內容中，尋找 roles/container.defaultNodeServiceAgent。

   2. 如果缺少角色，請授予 Kubernetes 預設節點服務代理人角色：

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:[e-mail]" \
          --role="roles/container.defaultNodeServiceAgent"
      

排解資源和效能問題

如果記錄間歇性遺失或從高流量節點捨棄，原因可能不是設定錯誤，而是效能問題。請參閱下列各節，調查專案是否超出 API 配額，或是記錄量過高，導致特定節點上的代理程式不堪負荷。

調查 Cloud Logging API 配額用量

為保護服務，Cloud Logging 會對所有專案強制執行寫入配額，限制 Cloud Logging 每分鐘可擷取的記錄總量。

症狀：

• 記錄間歇性或完全遺失。
• 您在節點或記錄代理程式記錄中看到與 RESOURCE_EXHAUSTED 相關的 logging.googleapis.com 錯誤。

原因：

專案超出 Cloud Logging API 寫入要求配額。這個問題會導致記錄代理程式無法傳送記錄。

解決方法：

如要查看配額用量並申請增加配額，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Quotas」(配額) 頁面。

   前往配額

2. 在「Filter」欄位中輸入 Cloud Logging API，然後按 Enter 鍵。

3. 在篩選後的清單中，找出叢集所在區域的「每個區域每分鐘的記錄寫入位元組數」配額。

4. 查看「目前用量百分比」欄中的值。如果用量已達到或接近上限，您可能已超出配額。

5. 如要申請提高配額，請點選「編輯配額」，然後按照提示操作。詳情請參閱「查看及管理配額」。

如要減少用量，請考慮排除記錄或降低應用程式的記錄詳細程度。您也可以設定快訊政策，在達到限制前收到通知。

調查節點輸送量和資源用量

每個節點上的 GKE 記錄代理程式都有自己的輸送量限制，可能會超出限制。

症狀：

特定節點的記錄會間歇性遺失或延遲，尤其是在叢集活動量高或節點資源使用量大的期間。

原因：

GKE 記錄代理程式設有預設的總處理量限制 (每個節點約 100 KBps)。如果節點上的應用程式產生記錄檔的速度超過這個限制，即使專案的整體 API 配額未超過，代理程式仍可能會捨棄記錄檔。您可以在 Metrics Explorer 中使用 kubernetes.io/node/logs/input_bytes 指標，監控節點記錄吞吐量。

如果節點的 CPU 或記憶體負載過重，導致代理程式沒有足夠資源處理記錄，也可能導致記錄遺失。

解決方法：

如要降低輸送量，請選取下列其中一個選項：

標準叢集

請嘗試下列解決方法：

• 啟用高處理量記錄功能：這項功能可提高每個節點的容量。詳情請參閱「調整 Cloud Logging 代理程式輸送量」。

• 減少記錄檔資料量：分析應用程式記錄模式。減少不必要或過於冗長的記錄。

• 部署自訂記錄代理程式：您可以部署及管理自己的自訂 Fluent Bit DaemonSet，但必須負責設定及維護。

• 檢查節點資源用量：即使記錄檔容量在限制範圍內，也請確保節點的 CPU 或記憶體不會過度負載。節點資源不足可能會妨礙記錄代理程式處理及傳送記錄。您可以在 Metrics Explorer 中查看 kubernetes.io/node/cpu/core_usage_time和 kubernetes.io/node/memory/used_bytes 等指標。

Autopilot 叢集

請嘗試下列解決方法：

• 減少記錄檔資料量：分析應用程式記錄模式。減少不必要或過於冗長的記錄。盡可能確保記錄檔結構化，因為這類記錄檔有助於有效處理。排除不必要的記錄。

• 提升應用程式效能：由於節點資源是在 Autopilot 叢集中管理，請確保應用程式不會過度消耗 CPU 或記憶體，否則可能會間接影響節點元件 (例如記錄代理程式) 的效能。雖然您不會直接管理節點，但應用程式效率會影響整體節點健康狀態。

排解篩選和應用程式問題

如果應用程式已成功產生記錄，但 Cloud Logging 仍未顯示，通常是篩選條件或應用程式的記錄行為所致。以下各節將探討記錄排除篩選器、容器層級緩衝、限制性搜尋查詢，以及未寫入 stdout 或 stderr 的應用程式等問題。

調查記錄排除篩選器

記錄檔探索工具只會顯示符合查詢中所有篩選條件和所選時間範圍的記錄檔。

症狀：

Cloud Logging 中缺少符合特定條件的特定記錄，但來自相同來源的其他記錄則存在。

原因：

記錄檔排除篩選器是在 Cloud Logging 接收器中定義 (通常是 _Default 接收器)。即使節點已成功傳送記錄，這些規則仍會根據特定條件，無聲無息地捨棄記錄。

解決方法：

如要查看及修改排除篩選器，請選取下列任一選項：

控制台

1. 前往 Google Cloud 控制台的「記錄檔路由器」頁面。

   前往記錄檔路由器

2. 找出有問題的篩選器：

   1. 針對每個接收器 (_Required 接收器除外，因為該接收器無法有排除篩選器)，按一下 「More actions」(更多動作)，然後選取「View sink details」(查看接收器詳細資料)。
   2. 查看「排除篩選器」部分中的查詢。根據遺失記錄的屬性 (例如資源類型、標籤或關鍵字) 比較篩選器邏輯。
   3. 複製排除篩選器查詢。

   4. 前往「Logs Explorer」頁面。

      前往 Logs Explorer

   5. 將排除篩選條件查詢貼到查詢窗格，然後按一下「執行查詢」。

   6. 查看結果。顯示的記錄是篩選器會排除的記錄。如果這些結果中顯示您遺失的記錄，可能就是這個篩選器造成。

3. 停用或編輯篩選器：

   1. 返回「記錄檔路由器」頁面。
   2. 按一下具有可疑篩選器的接收器「更多動作」圖示 ，然後選取「編輯接收器」。
   3. 找出「選擇要從接收器排除的記錄檔」部分，然後找到排除篩選器。
   4. 您可以按一下「停用」停用篩選器，或修改查詢條件，讓篩選器更精確。
   5. 按一下「更新接收器」。變更會套用至新記錄。

gcloud

1. 列出專案中的所有接收器：

   gcloud logging sinks list --project=PROJECT_ID
   

2. 查看每個接收器的排除篩選器：

   gcloud logging sinks describe SINK_NAME --project=PROJECT_ID
   

   在輸出內容中，查看 exclusions 區段。比對篩選器邏輯與遺失記錄的屬性 (例如資源類型、標籤或關鍵字)。

3. 如要修改排除條件，請更新接收器的設定：

   1. 將接收器的設定匯出至本機檔案 (例如 sink-config.yaml)：

      gcloud logging sinks describe SINK_NAME \
          --format=yaml > sink-config.yaml
      

   2. 使用文字編輯器開啟 sink-config.yaml 檔案。

   3. 找出 exclusions: 區段，然後移除或修改有問題的篩選器。

   4. 更新修改後的接收器：

      gcloud logging sinks update SINK_NAME sink-config.yaml \
          --project=PROJECT_ID
      

      如要進一步瞭解這個指令，請參閱 gcloud logging sinks update 說明文件。

調查容器記錄緩衝和延遲問題

應用程式和作業系統通常會使用緩衝區，以區塊形式寫入資料，而非逐行寫入，這樣可以提升效能。

症狀：

• 特定容器的記錄只會在容器結束後顯示在 Cloud Logging 中，或記錄顯示時會出現明顯延遲。
• 有時記錄不完整。

原因：

這個問題通常是由記錄緩衝區造成。雖然連線至終端機時，標準輸出 (stdout) 通常會進行行緩衝處理，但輸出內容透過管道傳輸時，這種行為會有所改變。如果容器中的應用程式記錄或啟動指令碼透過管道 stdout 傳送至其他指令 (例如 my-app | grep ...)，輸出內容可能會完全緩衝處理。因此，記錄會保留到緩衝區已滿或管道關閉為止。如果容器意外終止，這種行為可能會導致延遲或資料遺失。應用程式內部緩衝也可能導致延遲。

解決方法：

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

• 避免管道 stdout：如有可能，請修改容器進入點或應用程式指令，直接將記錄寫入 stdout 或 stderr，而不要透過容器中的 grep 或 sed 等其他指令管道。
• 確保行緩衝：
  • 如果無法避免管道，請使用支援行緩衝的工具。例如，使用 grep --line-buffered。
  • 如果是自訂應用程式，請確保應用程式在寫入 stdout 時經常清除記錄，最好是在每行之後。許多記錄程式庫都有控制緩衝區的設定。

• 測試緩衝行為：部署下列 Pod 資訊清單，並使用 kubectl logs -f buffered-pod 指令觀察記錄檔中的效果。在 buffered-container 資訊清單中，註解及取消註解不同的 command 陣列，藉此進行實驗：

  # buffered.yaml
  apiVersion: v1
  kind: ConfigMap
  metadata:
  name: run-script
  data:
  run.sh: |
      #!/bin/bash
      echo "Starting..."
      for i in $(seq 3600); do
      echo "Log ${i}"
      sleep 1
      done
      echo "Exiting."
  ---
  apiVersion: v1
  kind: Pod
  metadata:
  name: buffered-pod
  spec:
  containers:
      - name: buffered-container
      image: ubuntu  # Or any other image with bash
  
      # Case 1: Direct execution - line buffered by default to TTY
      # Logs appear immediately.
      command: ['/bin/bash', '-c', '/mnt/run.sh']
  
      # Case 2: Piped to grep - fully buffered by default
      # Logs might be delayed or appear in chunks.
      # command: ['/bin/bash', '-c', '/mnt/run.sh | grep Log']
  
      # Case 3: Piped to grep with --line-buffered
      # Logs appear immediately.
      # command: ['/bin/bash', '-c', '/mnt/run.sh | grep --line-buffered Log']
  
      volumeMounts:
          - name: scripts
          mountPath: /mnt
  volumes:
      - name: scripts
      configMap:
          name: run-script
          defaultMode: 0777
  restartPolicy: Never
  

調查記錄檔探索工具查詢

如果您確定系統正在收集記錄，但找不到記錄，可能是搜尋查詢或時間範圍有問題。

症狀：

您知道應用程式會產生記錄，但搜尋結果中未顯示預期記錄。

原因：

記錄檔探索工具中的查詢可能含有篩選器 (例如針對命名空間、標籤、資源類型或文字)，導致您要尋找的記錄遭到排除。

解決方法：

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

   前往 Logs Explorer

2. 按一下「挑選時間範圍」。即使您認為自己知道記錄檔的發生時間，也請嘗試大幅擴大範圍，排除時間問題。

3. 簡化查詢：

   1. 清除所有篩選條件。

   2. 請嘗試只依叢集篩選：

      resource.type="k8s_container"
      resource.labels.cluster_name="CLUSTER_NAME"
      resource.labels.location="LOCATION"
      

      更改下列內容：

      • CLUSTER_NAME：叢集名稱。
      • LOCATION：叢集的 Compute Engine 區域或可用區 (例如 us-central1 或 us-central1-a)。

   3. 點選「執行查詢」

4. 如果廣泛查詢有效，請逐一重新導入原始篩選器：

   • 資源類型：請務必使用正確的資源類型。舉例來說，您是否應該依 k8s_node 篩選，卻依 k8s_container 篩選？
   • 標籤：請仔細檢查 resource.labels 的拼字，例如 namespace_name、container_name 或自訂標籤。
   • 嚴重性：確認嚴重程度等級 (例如 severity=ERROR) 不會過於嚴格。
   • 文字酬載：檢查搜尋字詞是否有拼字錯誤和過於嚴格的字串。舉例來說，如果想使用「包含」，請使用 :，而非完全相符的 = (jsonPayload.message:"error" 而非 jsonPayload.message="error")。

5. 確認篩選器是否會區分大小寫 (文字通常不會，但標籤可能區分)，確保值沒有隱藏字元或多餘空格，並檢查含有特殊字元的字詞是否需要加上引號。

6. 查看「時間軸」。新增篩選器時突然下降，有助於找出查詢中出現問題的部分。

如需有效記錄查詢的更多建議，請參閱 Cloud Logging 說明文件中的「快速尋找記錄項目」。

如果縮小查詢範圍後仍找不到記錄，問題可能不是查詢本身，而是本文件其他章節所述的問題。

調查應用程式專屬記錄行為

GKE 記錄代理程式只會收集寫入 stdout 和 stderr 串流的記錄。

症狀：

即使叢集中的其他記錄存在，Cloud Logging 中也不會顯示特定 Pod 或容器的記錄。

原因：

應用程式不會寫入 stdout 或 stderr。可能是設定錯誤，導致記錄檔寫入容器內的檔案，而記錄代理程式無法收集這些檔案。

應用程式也可能在輸出內容中混用 JSON 和非 JSON 文字。記錄代理程式的剖析器會預期單一串流提供一致的格式 (JSON 或文字)。如果應用程式設定為 JSON 記錄，但輸出的是純文字行，可能會導致剖析器中斷，進而導致記錄檔遭捨棄或錯誤擷取。

解決方法：

1. 找出缺少記錄的應用程式 Pod 名稱和命名空間：

   kubectl get pods -n NAMESPACE_NAME
   

2. 檢查容器記錄：

   • 如果 Pod 只有一個容器，請執行下列指令：

     kubectl logs POD_NAME \
         -n NAMESPACE_NAME
     

     更改下列內容：

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

   • 如果 Pod 有多個容器，請指定容器名稱：

     kubectl logs POD_NAME \
         -c CONTAINER_NAME \
         -n NAMESPACE_NAME
     

     將 CONTAINER_NAME 替換為 Pod 內的容器名稱。

   • 如要即時追蹤記錄，請執行下列指令：

     kubectl logs -f POD_NAME \
         -c CONTAINER_NAME \
         -n NAMESPACE_NAME
     

     更改下列內容：

     • POD_NAME：Pod 的名稱。
     • CONTAINER_NAME：Pod 內的容器名稱。
     • NAMESPACE_NAME：Pod 的命名空間。

3. 分析輸出內容：

   • 如果 kubectl logs 指令沒有輸出內容，或指令輸出內容未包含預期記錄，則問題出在應用程式本身。kubectl logs 指令會直接從容器執行階段擷取的 stdout 和 stderr 串流讀取資料。如果這裡沒有記錄，表示 GKE 的記錄代理程式無法查看這些記錄。

     變更應用程式的程式碼或設定，停止寫入檔案，改為直接將所有訊息記錄到 stdout (一般記錄) 和 stderr (錯誤記錄)。

   • 如果看到 JSON 字串和純文字行混雜，表示輸出內容的格式不一致。將應用程式設定為只將有效的單行 JSON 物件寫入 stdout 和 stderr。

   • 如果 kubectl logs 指令確實顯示預期記錄，問題可能出在記錄管道的後續階段 (例如代理程式、權限或 Cloud Logging 服務)。

排解平台和服務問題

以下各節有助於調查直接設定以外的問題，例如記錄檔保留政策、Cloud Logging 健康狀態或不支援的 GKE 版本。

調查記錄保留期限

記錄會儲存在 bucket 中，每個 bucket 都有保留期限，規定記錄在自動刪除前可保留多久。

症狀：

系統會遺失特定日期之前的記錄。

原因：

您要搜尋的記錄早於記錄 bucket 的保留期限。

解決方法：

如要找出並更新保留期限，請選取下列其中一個選項：

控制台

1. 找出 GKE 記錄檔的路由目的地 bucket：

   1. 前往 Google Cloud 控制台的「記錄檔路由器」頁面。

      前往記錄檔路由器

   2. 查看「目的地」欄，瞭解記錄檔的遞送位置。

      目的地類似於下列內容：

      logging.googleapis.com/projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID
      

      請注意 PROJECT_ID、LOCATION 和 BUCKET_ID。

      記錄通常會轉送至 _Default bucket，但如果您已設定自訂接收器，記錄也可能會轉送至其他 bucket。

2. 檢查記錄檔 bucket 保留期限：

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

      前往「記錄檔儲存空間」

   2. 找出與接收器目的地相符的 bucket：BUCKET_ID、LOCATION 和 PROJECT_ID。

   3. 查看每個相關值區的「保留期限」欄。

   4. 如果想查看的記錄早於保留期限，Cloud Logging 就會刪除這些記錄。如需較長的保留期限，請按照下列步驟操作：

      1. 找出要延長保留期限的 bucket，然後按一下「更多動作」。
      2. 選取「編輯 Bucket」，然後更新保留期限。 請注意可能產生的費用影響。

gcloud

1. 找出 GKE 記錄檔的路由目的地 bucket：

   gcloud logging sinks list --project=PROJECT_ID
   

   查看輸出內容。每個接收器的 destination 欄位都會顯示記錄的路由位置。記錄 bucket 的目的地格式為：

   logging.googleapis.com/projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID
   

   請注意 PROJECT_ID、LOCATION 和 BUCKET_ID。

   記錄檔通常會轉送至 _Default 值區。

2. 檢查記錄檔 bucket 保留期限：

   gcloud logging buckets describe BUCKET_ID \
       --location=LOCATION \
       --project=PROJECT_ID
   

   在輸出中，找出 retentionDays 欄位。如果所需記錄的建立時間早於 retentionDays 列出的值，則 Cloud Logging 已刪除這些記錄。

3. 如需更長的保留期限，請更新設定：

   gcloud logging buckets update BUCKET_ID \
       --location=LOCATION \
       --retention-days=RETENTION_DAYS \
       --project=PROJECT_ID
   

   更改下列內容：

   • BUCKET_ID：記錄 bucket 的 ID。
   • LOCATION：儲存空間的 Compute Engine 區域或可用區 (例如 us-central1 或 us-central1-a)。
   • RETENTION_DAYS：記錄保留天數。請注意，延長保留期限可能會增加費用。
   • PROJECT_ID：您的 Google Cloud 專案 ID。

調查 Cloud Logging 服務問題和擷取延遲

有時記錄管道本身可能會發生問題，可能是因為服務全面中斷，或是暫時性的大規模擷取延遲。

症狀：

• 多個專案或叢集發生大規模或間歇性記錄遺失。
• 記錄檔在 Logs Explorer 中顯示的時間大幅延遲。

原因：

• Cloud Logging 服務中斷：服務全面中斷的情況十分罕見，但一旦發生，可能會導致系統無法擷取記錄，進而造成大範圍延遲或記錄完全遺失。
• 記錄檔量過高：即使沒有官方中斷事件，專案或區域的記錄檔量過高，也可能暫時超出擷取服務的負荷，導致記錄檔延遲顯示。

解決方法：

• 如要查看 Google Cloud 服務狀態，請前往 Google Cloud服務健康狀態資訊主頁。尋找與 Cloud Logging 或 GKE 相關的未結事件。

• 請將可能的擷取延遲納入考量。如果記錄未立即顯示，且沒有任何進行中的事件，請稍待片刻，讓系統擷取記錄，尤其是記錄量較大時。請過幾分鐘後再查看一次。

調查叢集版本

GKE 會定期發布新版本，修正元件錯誤並提升效能，包括記錄代理程式。

症狀：

記錄問題與叢集版本限制有關。

原因：

叢集可能正在執行舊版或不支援的 GKE 版本，而這些版本有已知的記錄代理程式問題，或缺少特定記錄功能。

解決方法：

如要解決這個問題，請按照下列步驟操作：

1. 檢查叢集版本：

   gcloud container clusters describe CLUSTER_NAME \
       --location LOCATION \
       --format="value(currentMasterVersion)"
   

   更改下列內容：

   • CLUSTER_NAME：叢集名稱。
   • LOCATION：叢集的 Compute Engine 區域或可用區 (例如 us-central1 或 us-central1-a)。

2. 如要確認是否為支援的版本，請將這個版本與 GKE 發布時間表進行比較。

3. 如果叢集使用不支援的版本，請升級叢集。

後續步驟

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

  • 與 Cloud 客戶服務聯絡，建立支援案件。
  • 在 StackOverflow 上提問，並使用 google-kubernetes-engine 標記搜尋類似問題，向社群尋求支援。你也可以加入 #kubernetes-engine Slack 頻道，取得更多社群支援。
  • 使用公開版 Issue Tracker 開啟錯誤或功能要求。