排解連線至可靠資料來源的問題

本頁面說明如何解決 Config Sync 無法與單一事實來源建立連線時發生的問題。

驗證問題

如果驗證失敗，Config Sync 就無法連線至可靠來源。 下列各節說明如何解決部分驗證問題。

Git 伺服器的伺服器憑證驗證失敗

連線至私人 Git 伺服器時，系統會使用 TLS 驗證伺服器是否為正版。如要進行這項驗證，您必須提供可識別根憑證授權單位的憑證，以及任何可驗證 Git 伺服器身分的中繼憑證授權單位。如果 Git 伺服器憑證驗證失敗，表示無法建立信任鏈結。

如果收到伺服器憑證驗證失敗的錯誤訊息，可能的原因如下：

  • 未指定憑證授權單位憑證 (CACert)。如要修正這個問題，請將 CACert 新增為 Secret，並在 RootSync 或 RepoSync 物件的 spec.git.caCertSecretRef 欄位中參照該 Secret。
  • CACert 不完整。如要修正這個問題，請修正 CACert Secret，使其包含完整的信任鏈結，包括根憑證和任何中介憑證。
  • CACert 無效。如要修正這個問題，請從伺服器提供的憑證指定連結下載憑證鏈結，然後更新 CACert Secret。

無法掛接 Git Secret

如果 git-sync 容器嘗試將存放區與 Secret 同步時收到下列錯誤，表示 Git Secret 未成功掛接至 git-sync 容器：

KNV2004: unable to sync repo Error in the git-sync container: ERROR: can't configure SSH: can't access SSH key: stat /etc/git-secret/ssh: no such file or directory: lstat /repo/root/rev: no such file or directory

如果將 Git 存放區的驗證類型從 none、gcenode 或 gcpserviceaccount 切換為需要密鑰的其他類型，就可能導致錯誤。

如要解決這個問題，請執行下列指令，重新啟動 Reconciler Manager 和 Reconciler：

# Stop the reconciler-manager Pod. The reconciler-manager Deployment spins
# up a new Pod which can pick up the latest `spec.git.auth`.
kubectl delete po -l app=reconciler-manager -n config-management-system

# Delete the reconciler Deployments. The reconciler-manager recreates the
# reconciler Deployments with correct volume mount.
kubectl delete deployment -l app=reconciler -n config-management-system

設定問題

設定問題通常會導致 Config Sync 無法連線至真實來源。下列各節說明如何找出並解決常見的設定問題。

圖表名稱無效

從 Helm 存放區同步處理時，請務必為 spec.helm.chart 設定正確的值。圖表名稱不含存放區名稱、圖表版本或 .tgz。您可以使用 helm template 指令驗證圖表名稱。

設定目錄無效

檢查設定是否有錯誤，例如 ConfigManagement 物件中的 policyDir 值不正確，或是 RootSync 或 RepoSync 物件中的 spec.git.dir 或 spec.oci.dir 值不正確。您收到的任何 KNV2004 錯誤訊息都會包含目錄值；請根據 Git 存放區或 OCI 映像檔驗證該值。

Git 分支無效

檢查 git-sync 容器的記錄檔是否有 Remote branch BRANCH_NAME not found in upstream origin 或 warning: Could not find remote branch BRANCH_NAME to clone. 等錯誤。如未指定，預設分支會設為 master。

Git、Helm 或 OCI 憑證無效

檢查 Config Sync 記錄，找出 git-sync、helm-sync 或 oci-sync 容器是否發生下列錯誤：

  • Could not read from remote repository. Ensure you have the correct access rights and the repository exists.
  • Invalid username or password. Authentication failed for ...
  • 401 Unauthorized

如果是 Git 存放區，請確認 Git 憑證和 git-creds Secret 設定正確。

如果是 Helm 存放區，請確認 Helm 憑證設定正確。

如果是 OCI 映像檔，請確認 OCI 憑證設定正確無誤。

Git 存放區網址無效

檢查 git-sync 容器的記錄，確認是否有 Repository not found 等錯誤。

請確認你使用的網址格式正確無誤。舉例來說，如果您使用 SSH 金鑰組向 Git 存放區進行驗證，請確保設定 Config Sync 時為 Git 存放區輸入的網址使用 SSH 通訊協定。

Helm 存放區網址無效

檢查 helm-sync 容器的記錄，瞭解是否有 ...not a valid chart repository 等錯誤。您可以使用 helm template 指令驗證 Helm 存放區網址。

OCI 登錄網址無效

RootSync 或 RepoSync 物件的 spec.oci.image 或 spec.oci.dir 欄位值無效，可能會導致連線問題。確認這些值是否正確。舉例來說，如果您要從 OCI 登錄檔同步處理，網址應以 oci:// 開頭。

您也可以查看 oci-sync 容器的記錄檔，瞭解更多資訊。

網路問題

如果懷疑問題與叢集網路有關，請先按照這些疑難排解步驟操作。

無法解析主機：github.com

當 Config Sync 嘗試連線至 Git 存放區時，會使用 DNS 解析指定主機名稱的 IP。如果無法解析主機，通常表示 DNS 或叢集網路有問題。

如要診斷問題，請參閱「排解 GKE 中的 Cloud DNS 問題」或「排解 GKE 中的 kube-dns 問題」，具體取決於您使用的 DNS 供應商服務。

叢集內無法連上 Git 存放區

有時，git-sync 容器會在記錄中擲回錯誤，指出容器無法連線至存放區。例如，ssh: connect to host source.developers.google.com port 2022: Network is unreachable。如要修正問題，請調整叢集的防火牆或網路設定。

來源 API 要求數量過高

Config Sync 採用多執行個體策略，可擴充及隔離房客和錯誤網域。因此，每個 RootSync 和 RepoSync 物件都會取得自己的協調器例項。每個協調器執行個體都有自己的來源專屬 Sidecar，即 git-sync、oci-sync 或 helm-sync。這些 Sidecar 會輪詢資料來源。新增 RootSync 或 RepoSync 物件時，調解器輪詢真實來源所發出的 API 請求數量會隨之線性增加。因此，如果您有多個 RootSync 和 RepoSync 物件都輪詢相同的可靠資料來源，有時可能會對來源伺服器造成大量流量負載。

請考慮採取下列任一策略來解決這個問題：

  • 合併多個 RootSyncs 或 RepoSync 物件，減少發出來源 API 要求的調解器數量。
  • 將來源類型從 Git 變更為 OCI。與大多數 Git 伺服器相比，Artifact Registry 等 OCI 存放區的擴充性通常較佳，因為這類存放區可以水平擴充，不必在伺服器副本之間同步。

後續步驟

  • 如果問題仍未解決，請查看您的問題是否為已知問題。

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