疑難排解簡介

如果您在使用 Config Sync 時遇到困難，本頁面將介紹一些常見工具和程序，協助您找出並解決問題。

升級至支援的版本

建議您升級 Config Sync 至支援版本。 升級通常可以解決常見問題，並提供最新功能。

使用 nomos 指令列工具

nomos 指令列工具可提供有關 Config Sync 設定的重要洞察資料。嘗試判斷問題來源或需要與 Cloud 客戶服務團隊合作時，以下各節所述的指令特別實用。

查看 Config Sync 狀態

nomos status 指令會提供匯總資料和錯誤，協助您瞭解 Config Sync 安裝作業的狀況。nomos status 提供下列資訊：

• 每個叢集的安裝狀態
• 同步處理錯誤 (包括從 Git 讀取資料，以及協調變更)

建立錯誤報告

如果 Config Sync 發生問題，需要 Cloud Customer Care 協助，您可以使用 nomos bugreport 指令提供有價值的偵錯資訊。

這個指令會產生含有時間戳記的 ZIP 檔案，其中包含 kubectl 環境中 Kubernetes 叢集的相關資訊。這個檔案也包含 Config Sync Pod 的記錄。不包含透過 Config Sync 同步處理的資源資訊。

查看總覽資訊主頁

Config Sync 資訊主頁會顯示 Config Sync 管理的套件狀態，以及這些套件中資源的狀態。瀏覽這個資訊主頁，有助於快速瞭解 Config Sync 安裝狀態，並找出有問題的套件。

• 如要存取資訊主頁，請前往控制台的「Features」(功能) Google Cloud 部分，然後點選「Config」(設定) 頁面：

  前往「設定」

使用監控和記錄分析功能

監控 Config Sync 並查看記錄檔，有助於判斷錯誤來源，並深入瞭解任何非預期行為。

瞭解 Config Sync 指標

使用 Config Sync 指標，瞭解 Config Sync 的健康狀態。

監控 RootSync 和 RepoSync 物件

使用 Google Cloud 控制台或 Google Cloud CLI 安裝 Config Sync 時，系統會自動為您建立 RootSync 物件。設定從多個存放區同步處理時，您可以建立 RepoSync 物件，其中包含命名空間存放區的設定資訊。

監控這些物件可揭露有關 Config Sync 狀態的寶貴資訊。詳情請參閱「監控 RootSync 和 RepoSync 物件」。

使用服務水準指標 (SLI)

如要在 Config Sync 無法正常運作時收到通知，請使用 Config Sync SLI。

查詢記錄

您可以使用記錄檔探索工具，擷取、查看及分析 Config Sync 的記錄資料。這些記錄可能包含有價值的歷來資料，而當運算子或協調器 Pod 重新啟動時，nomos bugreport 不會擷取這些資料。如需有助於診斷問題的查詢範例，請參閱「查詢 Config Sync 記錄」。

使用 kubectl 指令列工具檢查資源

Config Sync 由多個自訂資源組成，您可以使用 kubectl 指令查詢這些資源。這些指令可協助您瞭解每個 Config Sync 物件的狀態。

您應瞭解 Config Sync 管理的 Kubernetes 資源相關資訊：

• config-management-system 是用來執行 Config Sync 所有核心系統元件的命名空間。
• configmanagement.gke.io 和 configsync.gke.io 是我們用於所有自訂資源的 API 群組。

範例

以下各節說明如何使用 kubectl 指令檢查 Config Sync。

列出自訂資源

• 如要取得自訂資源的完整清單，請執行下列指令：

  kubectl api-resources | grep -E "configmanagement.gke.io|configsync.gke.io"
  

• 如要使用個別自訂資源，請執行下列指令：

  kubectl get RESOURCE -o yaml.
  

  將 RESOURCE 替換為要查詢的資源名稱。

  舉例來說，您可以透過下列指令的輸出內容，檢查 RootSync 物件的狀態：

  kubectl get rootsync -n config-management-system -o yaml
  

檢查物件的符記註解

您可能想知道 Config Sync 上次更新受管理 Kubernetes 物件的時間。每個受管理物件都會註解 Git 提交的雜湊，表示上次修改時間，以及包含修改內容的設定路徑。

舉例來說，如要取得名為 namespace-readers 的 ClusterRoleBinding 註解，請執行下列指令：

kubectl get clusterrolebinding namespace-readers

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

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  annotations:
    configmanagement.gke.io/source-path: cluster/namespace-reader-clusterrolebinding.yaml
    configmanagement.gke.io/token: bbb6a1e2f3db692b17201da028daff0d38797771
  name: namespace-readers
...

詳情請參閱「標籤和註解」。

透過 Gemini Cloud Assist 加速診斷

預先發布版

這項產品或功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。 正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

有時即使使用前幾節討論的工具，問題原因也不會立即顯現。調查複雜案件可能需要耗費大量時間，且需要深入的專業知識。在這種情況下，Gemini Cloud Assist 就能派上用場。這項功能會自動偵測隱藏模式、找出異常狀況，並提供摘要，協助您快速找出可能原因。

Gemini for Google Cloud 產品仍處於早期技術階段，因此可能會生成看似合理卻與事實不符的輸出內容。使用 Gemini for Google Cloud products 的輸出結果前，請一律確認內容是否屬實。詳情請參閱「Gemini for Google Cloud 和負責任的 AI 技術」。

存取 Gemini Cloud Assist

如要存取 Gemini Cloud Assist，請完成下列步驟：

1. 前往 Google Cloud 控制台的任何頁面。

2. 在 Google Cloud 控制台工具列，點選「Open or close Gemini Cloud Assist chat」。

   「Cloud Assist」面板隨即開啟。如果系統顯示範例提示，您可以點選，也可以在「輸入提示」欄位中輸入提示。

查看範例提示

如要瞭解 Gemini Cloud Assist 如何提供協助，請參考下列提示範例：

主題	情境	提示範例	Gemini Cloud Assist 的用途
初始設定	平台工程師首次設定 Config Sync，以便從 Git 存放區管理 GKE 叢集。	如何設定 Config Sync，將 GitHub 存放區中的資訊清單同步至 GKE 叢集？	Gemini Cloud Assist 提供設定 Config Sync 的逐步指南，涵蓋機群註冊和啟用功能，並說明存放區網址、分支、路徑和驗證方法 (例如 public、token 或 ssh) 等詳細資料。
排解同步錯誤	開發人員提交新的資訊清單，但資源無法套用至叢集，且同步狀態顯示錯誤代碼。	我的 Config Sync RootSync 物件顯示「KNV2009: the server could not find the requested resource」。這是什麼意思？如何修正？	Gemini Cloud Assist 會分析錯誤代碼，說明這通常表示 Config Sync 無法找到或與預期的 Kubernetes 資源互動。接著詳細說明常見原因，包括缺少 RBAC 權限、超出資源物件大小限制、目錄路徑不正確、外部目錄衝突，以及非受管理資源的問題，並針對每個原因提供具體的疑難排解步驟。
管理多個團隊	機構需要允許應用程式團隊在特定命名空間中管理自己的設定，但不能授予他們中央平台存放區的存取權。	在 Config Sync 中，RootSync 物件和 RepoSync 物件有何不同？使用時機RepoSync	Gemini Cloud Assist 說明 RootSync 和 RepoSync 物件之間的核心差異：RootSync 物件屬於叢集範圍，通常由管理員用於叢集範圍的設定；RepoSync 物件屬於命名空間範圍，專供應用程式團隊管理特定命名空間內的資源，以促進委派和多租戶架構。 Gemini Cloud Assist 也會詳細說明應使用 RepoSync 物件的情境，強調其在多租戶方面的優點，以及減少錯誤設定的影響範圍。
主動驗證	開發人員想確保新資訊清單有效，再將其提交至存放區，以免中斷實際執行環境中的同步作業。	將 Kubernetes 資訊清單推送至 Git 存放區前，如何在本機檢查 Config Sync 錯誤？	Gemini Cloud Assist 說明如何使用 nomos 指令列工具，檢查 Kubernetes 資訊清單是否有 Config Sync 錯誤。本文詳細說明如何使用 nomos vet 指令驗證語法，以及如何使用 nomos hydrate 指令預覽 Kustomize 或 Helm 轉譯的設定。Gemini Cloud Assist 也會列出建議的工作流程，方便您在推送至 Git 前整合這些檢查。

詳情請參閱下列資源：

• 瞭解如何撰寫更優質的提示。
• 瞭解如何使用 Gemini Cloud Assist 面板。
• 閱讀「Gemini for Google Cloud 總覽」。
• 瞭解 Gemini for Google Cloud 如何使用您的資料。

使用 Gemini Cloud Assist Investigations

除了互動式對話，Gemini Cloud Assist 還能透過 Gemini Cloud Assist Investigations 執行更深入的自動分析。這項功能直接整合至記錄檔總管等工作流程，是強大的根本原因分析工具。

從錯誤或特定資源啟動調查時，Gemini Cloud Assist 會分析記錄、設定和指標。系統會使用這項資料，針對可能的原因產生排序後的觀察結果和假設，然後提供建議的後續步驟。您也可以將這些結果轉移至 Google Cloud 支援案件，提供有價值的背景資訊，協助您更快解決問題。

詳情請參閱 Gemini 說明文件中的「Gemini Cloud Assist Investigations」。

閱讀其他疑難排解文件

如果問題仍未解決，請參考下列資源：

• 如果收到錯誤訊息，請參閱錯誤參考資料頁面，瞭解如何解決錯誤。

• 檢查問題是否由已知問題造成。

• 如果特定領域有困難，請參閱目錄中「依問題類型排解問題」一節列出的疑難排解指南。

後續步驟

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

  • 與 Cloud 客戶服務聯絡，建立支援案件。
  • 在 StackOverflow 上提問，向社群尋求支援。如果您使用 kpt 或 Kustomize，請使用 kpt 或 kustomize 標記搜尋類似問題。
  • 使用 GitHub 上的公開 Issue Tracker 回報錯誤或提出功能要求。