錯誤參考資料

本頁說明 Config Sync 錯誤代碼，以及處理這些錯誤的建議做法。

Config Sync 錯誤訊息包含採用 KNV1234 格式 (1234 是專屬編號) 的錯誤 ID，後面加上問題說明和建議的修正方法。K 是從 Kubernetes 慣例繼承而來，前置字元為 N 的規則專屬於 nomos，V 則專屬於可在存放區和叢集初始狀態中偵測到的錯誤。存放區和叢集初始狀態中可偵測到的錯誤代碼格式為 KNV1XXX。只能在執行階段偵測到的錯誤代碼格式為 KNV2XXX。

KNV 錯誤表格

錯誤代碼 說明 建議做法

InternalError 的 ID 已變更為 KNV9998， Config Sync 版本為 1.6.1。

不適用

Config Sync 1.3 版已淘汰此功能。

不適用

Config Sync 1.3 版已淘汰此功能。

不適用

使用階層式存放區結構時，內含命名空間設定的目錄不得包含任何子目錄。

沒有命名空間設定的目錄是抽象命名空間目錄，且包含從該目錄沿用的目錄。因此，抽象命名空間目錄必須有子目錄。包含命名空間設定的目錄為命名空間目錄，但無法成為沿用來源，因此不得含有任何子目錄。

請從上層目錄移除命名空間設定，或是將子目錄移至其他位置。

叢集範圍內的物件不得宣告 configmanagement.gke.io/namespace-selector 註解。NamespaceSelector 只能針對命名空間範圍內的物件宣告。

從 metadata.annotations 欄位移除 configmanagement.gke.io/namespace-selector。

管理註解的唯一有效設定為 configmanagement.gke.io/managed=disabled。這項設定用於明確取消管理 Git 存放區中的資源，同時保留已簽入的設定。註解 configmanagement.gke.io/managed=enabled 並非必要。

確認管理註解為 configmanagement.gke.io/managed=disabled。 configmanagement.gke.io/managed=disabled。

詳情請參閱「管理物件」。

無法剖析在存放區中宣告的物件。

驗證 YAML 格式。舉例來說，您可以使用 kubectl --validate 指令。

如果 nomos vet 在具有 group: configsync.gke.io的類型 (例如 RepoSync) 上傳回這項錯誤，請從 v1.6.0-rc.6或更新版本下載 下載頁面解決問題。

使用非結構化存放區時，設定不得在抽象命名空間目錄中宣告。

將錯誤訊息中列出的設定移至命名空間目錄。

詳情請參閱「使用非結構化存放區」。

使用階層式存放區結構時，設定必須宣告與包含設定的命名空間目錄相符的命名空間，或省略該欄位。

更新錯誤訊息中識別的命名空間欄位。

詳情請參閱「階層式存放區結構」。

設定不得宣告開頭為 configmanagement.gke.io 的不支援註解。

請確認你使用的是下列其中一種支援的註解：

設定的標籤不能有開頭為 configmanagement.gke.io/ 的金鑰。這個標籤金鑰前置字串已預留供 Config Sync 使用。

更新錯誤訊息中指出的所有標籤。舉例來說，如果您嘗試宣告名為
configmanagement.gke.io/example-label: label-value 的標籤，可以將其變更為
example-label: label-value。

Config Sync 1.3 版已淘汰此功能。

 不適用

設定參照了不存在的 ClusterSelector 或 NamespaceSelector。您必須先建立選取器，才能在設定的註解中使用選取器。

建立所有缺少的選取器，或移除參照已移除選取器的所有設定。

ClusterSelector 和 NamespaceSelector 設定使用正確的語法，但系統發現了語法錯誤。

請務必使用適當的資料結構定義指定設定：

Config Sync 1.3.2 版已淘汰此功能。 不適用

使用階層式存放區結構時，存放區的 system/ 目錄中必須有 ConfigManagement Operator 的設定。這項設定必須包含必要資訊，例如存放區的語意版本。

請至少定義 ConfigManagement Operator 的最簡單設定。詳情請參閱階層式存放區的結構。
Config Sync 1.3 版已淘汰此功能。 不適用

使用階層式存放區結構時，您「不得」直接在 namespaces/ 目錄中宣告命名空間。

為錯誤訊息中列出的命名空間設定建立子目錄。詳情請參閱「階層式存放區結構」。
使用階層式存放區結構時，命名空間設定會宣告 metadata.name，且其值必須與命名空間目錄的名稱相符。 修正命名空間的 metadata.name 或目錄。

叢集中未定義資源的 CustomResourceDefinition。

為錯誤訊息中參照的資源建立 CustomResourceDefinition。 如果資源類型不是 Kubernetes 內建物件，就必須有 CustomResourceDefinition。

使用階層式存放區時，這類設定無法在 system/ 目錄中宣告。

將錯誤訊息中參照的資源移出 system/ 目錄。詳情請參閱「階層式存放區結構」。

Repo 設定中的 spec.version 欄位代表該存放區的語意版本。這個錯誤指出，系統不支援您使用的版本。

如果存放區格式與支援版本相容，請更新 spec.version 欄位。如需升級，請按照版本資訊中的指示操作。

目錄名稱不得超過 64 個半形字元，只能使用小寫英數字元或「-」，且開頭和結尾須為英數字元。

重新命名或移除名稱有誤的目錄。

相同種類的設定在相同命名空間和父項抽象命名空間中，名稱不得重複。

重新命名或移除錯誤訊息中提及的設定，確保所有設定都有專屬名稱。

同一個目錄中不得有多個命名空間資源。

移除重複的設定，確保命名空間資源數量不超過一個。

所有設定都必須宣告 metadata.name。

在有問題的設定中新增 metadata.name 欄位。

如果 sourceFormat 設為 unstructured，則不允許使用 Repo.configmanagement.gke.io 類型。

移除有問題的設定，或將存放區轉換為使用 sourceFormat: hierarchy。

如果您使用階層式存放區，只能在 system/ 目錄中宣告 HierarchyConfig 和 Repo 種類。

請確認 system/ 目錄中宣告的任何設定，都是允許的種類。如果不是，請將其移至其他目錄。

禁止宣告 config-management-system、resource-group-system 和 config-management-monitoring，或其中的資源。

如果您已宣告 config-management-system 命名空間，請移除該命名空間和其中的任何設定。

如果您已宣告 resource-group-system 或 config-management-monitoring 命名空間，請取消管理控制器命名空間：

  1. 更新 Config Sync，停止管理命名空間和底下宣告的任何資源。
  2. 等待同步完成，然後確認叢集上仍有對應資源，但 nomos status 中沒有。
  3. 從來源中移除控制器命名空間 YAML 檔案。
  4. 讓 Config Sync 繼續管理資源。

如果您先前是同步至階層式存放區，且必須一併宣告控制器命名空間和任何資源，建議改用非結構化存放區，以便更彈性地調整來源結構。

提供的 metadata.name 格式無效。

變更 metadata.name 以滿足下列條件：

  • 長度少於 254 個字元
  • 由小寫英數字元、「-」或「.」組成
  • 開頭和結尾須為英數字元

如果 metadata.name 無效，且原始資源支援這項功能，請考慮改用 spec.resourceID 欄位，這樣就不會受到這些限制。詳情請參閱「使用 resourceID 欄位管理資源」。

Config Sync 1.3 版已淘汰此功能。 不適用

禁止在 namespaces/ 目錄外宣告命名空間範圍內的物件。

將有問題的設定移至合法目錄。如要進一步瞭解命名空間範圍內的物件，請參閱「命名空間範圍內的物件」。

禁止在 cluster/ 目錄外宣告叢集範圍物件。

將有問題的設定移至合法目錄。如要進一步瞭解叢集範圍內的物件，請參閱「叢集範圍內的物件」。
Config Sync 1.3 版已淘汰此功能。 不適用

這個資源種類不得在 HierarchyConfig 中宣告。

移除有問題的資源。如要進一步瞭解 HierarchyConfig，請參閱「停用某個物件類型的沿用機制」。

系統在 HierarchyConfig 上偵測到 HierarchyMode 的無效值。

將 HierarchyMode 變更為 none 或 inherit。如要進一步瞭解 HierarchyConfig，請參閱「停用物件類型的繼承功能」。

Config Sync 無法設定這個物件。

 從存放區中移除有問題的設定。

含有設定的抽象命名空間目錄至少須有一個命名空間子目錄。

請在抽象命名空間目錄下新增命名空間目錄，或在抽象命名空間目錄中新增命名空間設定，或移除抽象命名空間目錄中的設定。

不允許使用指定 metadata.ownerReference 的設定。

從來源存放區移除「status」欄位。如要移除您不擁有的第三方設定，請使用 kustomize patches 大量移除資訊清單中指定的 status 欄位。

這個 HierarchyConfig 參照的資源具有叢集範圍。HierarchyConfig 不允許叢集範圍物件。

更新 HierarchyConfig，使其不再參照有問題的資源。

您無法移除自訂資源定義 (CRD)，並將對應的自訂資源留在存放區中。

移除 CRD 和自訂資源。

CustomResourceDefinition 的名稱無效。

將名稱變更為錯誤訊息中建議的名稱。

設定檔使用的群組和類別已淘汰。

將 Group 或 Kind 變更為錯誤訊息中的建議。

叢集範圍內的資源不得宣告 metadata.namespace。

 從叢集範圍資源中移除「metadata.namespace」欄位。

命名空間範圍內的資源必須宣告 metadata.namespace 或 metadata.annotations.configmanagement.gke.io/namespace-selector。

在命名空間範圍的資源中新增缺少的欄位。

設定含有無效的註解值。

按照錯誤訊息中的指示解決錯誤。

metadata.namespace 的值不是有效的 Kubernetes 命名空間名稱。

更新 metadata.namespace 的值，確保符合下列規則：

  • 長度不得超過 63 個字元
  • 只能包含小寫字母 (a-z)、數字 (0-9) 和連字號「-」
  • 開頭和結尾為小寫字母或數字

資源是在非受管理命名空間中宣告。

請移除 configmanagement.gke.io/managed: disabled 註解，或將註解新增至已宣告的資源。

資源含有無效標籤。

移除錯誤訊息中列出的違法標籤。

命名空間存放區只能在套用存放區的命名空間中，宣告命名空間範圍內的資源。

請確認所有命名空間存放區都正確宣告命名空間範圍內的資源。 舉例來說，shipping 命名空間存放區的存放區只能管理 shipping 命名空間中的資源。metadata.namespace 的值為選用項目。根據預設，Config Sync 會假設命名空間存放區中的所有資源都屬於該命名空間。

舉例來說，如果 shipping 命名空間存放區中的設定宣告了 metadata.namespace: billing，您就會收到錯誤訊息。

除了確保正確宣告命名空間範圍的資源，也請確認命名空間是在根存放區中宣告。這是必要步驟，因為命名空間屬於叢集範圍。

命名空間存放區最多可宣告一個 Kptfile 資源。

 移除所有 Kptfile 資源，只保留一個。

在多個單一事實來源中管理物件時，如果同一個物件 (相符的群組、種類、名稱和命名空間) 在多個來源中宣告，就可能發生衝突。

舉例來說，如果 RootSync 和 RepoSync 管理同一個物件，則 RootSync 會勝出。如果 RootSync 先套用，RepoSync 會回報 KNV1060 狀態錯誤。如果 RepoSync 先套用，RootSync 會覆寫 RepoSync 的物件，且 RepoSync 在看到更新時會回報 KNV1060 狀態錯誤。

如要解決衝突，請更新設定以符合其他單一資料來源，或從其中一個來源刪除衝突的物件。

nomos vet 指令一次只會檢查一個存放區的錯誤，因此無法偵測到這個問題。

InvalidRepoSyncError 報告 RepoSync 設定有誤。 必須正確設定 RepoSync 物件，Config Sync 才能從命名空間存放區同步處理設定。

按照錯誤訊息中的說明修正設定錯誤。

Kptfile 沒有有效的目錄欄位。Kptfile 應具有非空白的清單欄位，且指定了 ID 和命名空間。

在 Kptfile 中指定 .inventory.identifier 和 .inventory.namespace 的值。

在根存放區中找到 Kptfile。Kptfile 僅支援命名空間範圍內的存放區。

從根存放區中移除 Kptfile。

無法剖析存放區中的 api-resources.txt 檔案。

按照錯誤訊息中的指示操作。舉例來說，您可能需要重新執行 kubectl api-resources > api-resources.txt。

CustomResourceDefinition 格式有誤。

檢查錯誤訊息中指定的欄位，確認其值格式正確。

設定物件只能宣告 cluster-selector 註解。如果同時存在舊版註解 (configmanagement.gke.io/cluster-selector) 和行內註解 (configsync.gke.io/cluster-name-selector)，就會發生這個錯誤。

從 metadata.annotations 欄位中移除其中一個註解。

協調器無法將宣告的欄位編碼為與伺服器端套用相容的格式。 原因可能是結構定義過舊。

檢查錯誤訊息指定的欄位，並確認該欄位符合資源種類的結構定義。

轉譯程序發生使用者可解決的問題。

如果 Git 存放區包含 Kustomize 設定，但 Git 同步目錄中沒有 kustomization.yaml 檔案，請在同步目錄中新增 kustomization.yaml，觸發算繪程序，或從所有子目錄中移除 kustomization.yaml，略過算繪程序。

如果錯誤是由 kustomize build 失敗所致，您可能需要更新 Git 存放區中的 Kustomize 設定。您可以使用 nomos hydrate 和 nomos vet 分別在本機預覽及驗證更新後的設定。如果更新後的設定順利算繪，您可以推送新的提交內容，修正 KNV1068 錯誤。

如果從公開存放區提取遠端基準時發生 kustomize build 錯誤，您需要將 spec.override.enableShellInRendering 設為 true。

協調器已協調自身的 RootSync 或 RepoSync 物件。RootSync 物件可以管理其他 RootSync 和 RepoSync 物件；RepoSync 物件可以管理其他 RepoSync 物件，但無法自我管理。

從物件同步來源的真實來源中，移除 RootSync 或 RepoSync 物件。

要求存取檔案系統資源的作業系統層級系統呼叫失敗。

這個錯誤可能是因為 YAML 設定無效或使用特殊字元。如果 YAML 設定無效，您會看到類似下列內容的錯誤訊息： KNV2001: yaml: line 2: did not find expected node content path:...。如要解決這個問題，請檢查 YAML 檔案並解決任何設定問題。這可能是存放區中的任何 YAML 設定所致。

如果檔案名稱或路徑含有特殊字元，您可能會看到類似 KNV2001: yaml: control characters are not allowed path:/repo/source/.../._pod.yaml 的錯誤訊息。在此範例中，「._pod.yaml」不是有效檔案名稱。如要解決這個問題，請從檔案或路徑名稱中移除特殊字元。

存取 Kubernetes API 伺服器的要求失敗。

Kubernetes API 要求可能會因各種原因而失敗。常見原因包括：

  • API 探索錯誤
  • 用戶端或伺服器端要求或回應逾時
  • 身分識別、驗證或授權錯誤
  • 網路連線錯誤
  • Webhook 拒絕要求
  • Webhook 健康狀態不良或 API 伺服器無法連線

發生大多數 API 伺服器錯誤時，Config Sync 會重試。有些問題可能會自行解決，但大多數都需要使用者介入才能解決。API 伺服器錯誤很少是由 Config Sync 本身所造成，但如果您懷疑可能是這個原因，請提交錯誤報告。

一般的作業系統層級系統呼叫失敗。

Config Sync 無法從可靠來源讀取資料。

造成這項錯誤的原因有很多，如要排解連線至單一事實來源的問題，請參閱「排解連線至單一事實來源的問題」。如要瞭解導致 KNV2004 錯誤的已知問題，請參閱「已知問題」。
Config Sync 正在與另一個控制器爭奪資源。 這類爭鬥會耗用大量資源，並可能導致效能降低。 如需診斷及解決控制器衝突問題的訣竅，請參閱「排解控制器衝突問題」。

為避免誤刪，Config Sync 不允許您在單一提交中移除所有命名空間或叢集範圍的資源。

如果已停用 Config Sync 許可控制 Webhook，請還原刪除所有資源的提交。
如果已啟用 Config Sync 許可網路鉤子，命名空間可能會無法終止。如要修正這個問題，請按照下列步驟操作：

  1. 停用 Config Sync，並等待所有資源清除完畢或處於穩定狀態。舉例來說，您可以執行 kubectl get ns，確認命名空間已刪除。
  2. 重新啟用 Config Sync。
  3. 還原刪除所有資源的提交。

如要刪除受管理的所有資源，請完成下列步驟：

  1. 在第一次提交時，移除所有命名空間或叢集範圍資源，但保留一個，並允許 Config Sync 同步處理這些變更。
  2. 在第二次提交中移除最後一個資源。

API 伺服器上的資源遭到修改或刪除，但 Config Sync 也嘗試修改該資源。

如果這類錯誤只會在啟動時或偶爾出現，可以忽略這些錯誤。

如果這些錯誤並非暫時性 (持續數分鐘)，可能表示有嚴重問題，請nomos status回報控制器衝突。

這是一般錯誤，表示 Config Sync 無法將部分設定同步至叢集。

造成這項錯誤的原因有很多，如需解決常見同步問題的提示，請參閱「排解同步問題」。

此為一般錯誤，指出單一或多項資源發生錯誤。

錯誤訊息會包含造成錯誤的特定資源。調查這些資源。

有特定的資源需要處理，但系統找不到該資源。舉例來說，ConfigManagement Operator 嘗試更新某項資源，但該資源已經在系統計算更新時遭到刪除。

建立或還原遺失的資源。

這個錯誤回報，系統在只允許一個 APIResource 存在的位置，發現了多個 APIResource 執行個體。舉例來說，一個叢集上只能有一項 Repo 資源。

移除額外的 APIResource。

命名空間調解程式的權限不足，無法管理資源。

請確認對帳員具備足夠的權限。

如果 Config Sync 網頁 hook 設定遭到非法修改，就會出現這項警告。 系統會忽略違法的 Webhook 設定。

移除遭非法修改的 Webhook。

算繪程序發生內部問題。舉例來說， Config Sync 無法存取檔案系統。

這項錯誤可能表示 Pod 狀態不佳。您可以執行下列指令，重新啟動協調器 Pod：

# restart a root reconciler
kubectl delete pod -n config-management-system -l configsync.gke.io/reconciler=root-reconciler

# restart a namespace reconciler
kubectl delete pod -n config-management-system -l configsync.gke.io/reconciler=ns-reconciler-NAMESPACE

這個錯誤代表暫時性問題，稍後應會自動解決。 舉例來說，如果轉譯狀態與來源設定不符，您可能會看到這項錯誤。

系統應會自動解決這個錯誤。

Config Sync 本身有問題。

請提交錯誤報告。

您遇到我們尚未記錄的錯誤。

我們還沒有針對您遇到的錯誤撰寫專屬的說明文件。

返回頁首

沒有 KNV 代碼的錯誤訊息

Config Sync 調解器回報的錯誤會顯示 KNV 錯誤代碼，但其他元件回報的錯誤不會顯示 KNV 代碼。舉例來說，權限遭拒錯誤來自於艦隊控制器，這是 Config Sync 之上的層級。

下表列出一些常見錯誤，但不含 KNV 前置字元。

錯誤訊息 建議做法

Error: cannot build exporters: error creating stackdriver exporter: cannot configure Google Cloud metric exporter: stackdriver: google: could not find default credentials.

Error: Permission monitoring.timeSeries.create denied (or the resource may not exist).

無法建構匯出工具

如果 Open Telemetry Collector 中的元件無法存取相同命名空間下的預設服務帳戶，您可能會發現 config-management-monitoring 下的 otel-collector Pod 處於 CrashLoopBackoff 狀態，或看到類似下列的錯誤訊息。

如果叢集啟用 Workload Identity Federation for GKE，通常會發生這個問題。

如要解決這個問題，請按照「監控 Config Sync」一文中的操作說明，授予預設服務帳戶指標寫入權限。

如果設定 IAM 後仍發生錯誤，請重新啟動 otel-collector Pod，讓變更生效。
如果您使用自訂監控解決方案，但已分叉預設 otel-collector-googlecloud ConfigMap，請檢查並重新設定任何差異。

server certificate verification failed. CAfile:/etc/ca-cert/cert CRLfile: none

伺服器憑證驗證失敗

如果 git-sync、helm-sync 或 oci-sync 容器無法擷取構件，您可能會看到這則錯誤訊息。

這則訊息表示伺服器已設定自訂憑證授權單位 (CA) 的憑證。不過，自訂 CA 設定不正確，導致容器無法從伺服器擷取資料。

如要解決這個問題，請先確認 RootSync 或 RepoSync 物件中的 caCertSecretRef 欄位是否已正確設定，並檢查 Secret 物件是否存在。

接著，如果已設定欄位且 Secret 物件存在，請確保 Secret 物件包含完整憑證。
視自訂 CA 的佈建方式而定，檢查完整憑證的方法可能有所不同。

以下範例說明如何列出伺服器憑證： 

echo -n | openssl s_client -showcerts -connect HOST:PORT -servername SERVER_NAME 2>/dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'

您可以要求網路管理團隊為您取得 CA 憑證。

Error message: "MESSAGE": "Unable to retrieve pull secret, the image pull may not succeed."

無法擷取提取密鑰，可能無法成功提取映像檔

如果您使用 Google Distributed Cloud 的私人登錄檔，Config Sync 安裝或升級作業可能會停滯。您會看到類似以下訊息的錯誤。

如要解決這個問題，請先按照「使用私人登錄檔更新 Config Sync」一文的步驟操作，再安裝或升級 Config Sync。
Permission 'gkehub.features.create' denied on 'projects/PROJECT_ID/locations/global/features/configmanagement'

權限遭拒

如果您嘗試設定 Config Sync 時收到類似以下範例的錯誤訊息，可能是因為您沒有 GKE Hub 管理員角色。

如要確認您具備必要權限，請確認您已授予必要的 IAM 角色。

返回頁首

後續步驟