排解 Google 服務帳戶的權限問題

本頁說明如何解決使用 Config Sync 和 Google 服務帳戶時發生的權限問題。

缺少讀者存取權

使用 Google 服務帳戶 (spec.git.gcpServiceAccountEmail、spec.oci.gcpServiceAccountEmail 或 spec.helm.gcpServiceAccountEmail) 向 Cloud Source Repositories 或 Artifact Registry 進行驗證時，Google 服務帳戶需要下列讀取者存取權：

  • Cloud Source Repositories：roles/source.reader
  • Artifact Registry：roles/artifactregistry.reader

如果服務帳戶缺少這些角色，git-sync、oci-sync 或 helm-sync 就會失敗，並顯示類似下列的錯誤：

failed to pull image us-docker.pkg.dev/...: GET https://us-docker.pkg.dev/v2/token?scope=repository...: DENIED: Permission \"artifactregistry.repositories.downloadArtifacts\" denied on resource \"projects/.../locations/us/repositories/...\" (or it may not exist)

"Err":"failed to render the helm chart: exit status 1, stdout: Error: failed to download ...

如要修正這個問題，請授予服務帳戶正確的讀取者存取權。

缺少與 Workload Identity Federation for GKE 的 IAM 政策繫結

使用 Google 服務帳戶進行驗證時，Google 服務帳戶與 Kubernetes 服務帳戶之間必須有 IAM 政策繫結。如果缺少 IAM 政策繫結，您會收到下列錯誤訊息：

KNV2004: unable to sync repo Error in the git-sync container: ERROR: failed to call ASKPASS callback URL: auth URL returned status 500, body: "failed to get token from credentials: oauth2/google: status code 403: {\n \"error\": {\n \"code\": 403,\n \"message\": \"The caller does not have permission\",\n \"status\": \"PERMISSION_DENIED\"\n }\n}\n"

如要修正這個問題，請建立下列 IAM 政策繫結：

gcloud iam service-accounts add-iam-policy-binding \
   --role roles/iam.workloadIdentityUser \
   --member "serviceAccount:PROJECT_ID.svc.id.goog[config-management-system/KSA_NAME]" \
   GSA_NAME@PROJECT_ID.iam.gserviceaccount.com

更改下列內容：

  • PROJECT_ID：如果您使用 GKE Workload Identity Federation for GKE，請新增貴機構的專案 ID。如果您使用機群 Workload Identity Federation for GKE，可以採用兩個不同的專案 ID。在 serviceAccount:PROJECT_ID 中，新增叢集註冊的機群專案 ID。在 GSA_NAME@PROJECT_ID 中，為任何可讀取 Cloud Source Repositories 中存放區的專案新增專案 ID。

  • KSA_NAME：調解程式的 Kubernetes 服務帳戶。如果是根存放區，如果 RootSync 名稱為 root-sync，則 KSA_NAME 為 root-reconciler。否則為 root-reconciler-ROOT_SYNC_NAME。

    如果是命名空間存放區，如果 RepoSync 名稱是 repo-sync，則 KSA_NAME 為 ns-reconciler-NAMESPACE。否則為 ns-reconciler-NAMESPACE-REPO_SYNC_NAME。

  • GSA_NAME：要用來連線至 Cloud Source Repositories 的自訂 Google 服務帳戶。請確認所選 Google 服務帳戶具備 source.reader 角色。

建立這項政策繫結需要 iam.serviceAccounts.setIamPolicy 權限。

請確保已在註冊的叢集上啟用機群 Workload Identity Federation for GKE。詳情請參閱「註冊叢集」。如果叢集所在的專案與車隊主機專案不同，您需要在車隊主機專案中，將 Google 服務帳戶與 Kubernetes 服務帳戶繫結。

缺少存取 Cloud Source Repositories 的 cloud-platform 範圍

將 Google 服務帳戶存取權授予 Cloud Source Repositories 中的 Git 存放區時，叢集節點的存取範圍必須包含唯讀範圍。

如要新增唯讀範圍，請在建立叢集時指定的 --scopes 清單中加入 cloud-source-repos-ro，或在建立叢集時使用 cloud-platform 範圍。例如：

gcloud container clusters create CLUSTER_NAME --scopes=cloud-platform

如果缺少唯讀範圍，您會看到類似下列內容的錯誤：

Error in the git-sync container: {"Msg":"unexpected error syncing repo, will retry","Err":"Run(git clone -v --no-checkout -b main --depth 1 https://source.developers.google.com/p/PROJECT_ID/r/csr-auth-test /repo/source): exit status 128: { stdout: \"\", stderr: \"Cloning into '/repo/source'...\\nremote: INVALID_ARGUMENT: Request contains an invalid argument\\nremote: [type.googleapis.com/google.rpc.LocalizedMessage]\\nremote: locale: \\\"en-US\\\"\\nremote: message: \\\"Invalid authentication credentials. Please generate a new identifier: https://source.developers.google.com/new-password\\\"\\nremote: \\nremote: [type.googleapis.com/google.rpc.RequestInfo]\\nremote: request_id: \\\"fee01d10ba494552922d42a9b6c4ecf3\\\"\\nfatal: unable to access 'https://source.developers.google.com/p/PROJECT_ID/r/csr-auth-test/': The requested URL returned error: 400\\n\" }","Args":{}}

缺少存取 Artifact Registry 的 storage-ro 範圍

使用 Artifact Registry 時，映像檔層會保留在 Cloud Storage bucket 中。將 Artifact Registry 中的 OCI 映像檔或 Helm Chart 的存取權授予 Google 服務帳戶時，叢集節點的存取範圍必須包含唯讀範圍。

如要新增唯讀範圍，請在建立叢集時指定的 --scopes 清單中加入 storage-ro，或在建立叢集時使用 cloud-platform 範圍。例如：

gcloud container clusters create CLUSTER_NAME --scopes=cloud-platform

如果缺少唯讀範圍，您會看到類似下列內容的錯誤：

Error in the oci-sync container: {"Msg":"unexpected error fetching package, will retry","Err":"failed to pull image us-docker.pkg.dev/...: GET https://us-docker.pkg.dev/v2/token?scope=repository%3A...%3Apull\u0026service=us-docker.pkg.dev: UNAUTHORIZED: failed authentication","Args":{}}

錯誤訊息可能不會提供導致錯誤的完整詳細資料，但會提供一個指令，用於輸出 git-sync 容器的記錄，其中可能包含更多資訊。

如果您已啟用 RootSync 或 RepoSync API，請執行下列指令：

kubectl logs -n config-management-system -l app=reconciler -c git-sync

如果尚未啟用 RootSync 或 RepoSync API，請執行下列指令：

kubectl logs -n config-management-system -l app=git-importer -c git-sync

如果您使用Google Cloud 控制台或 Google Cloud CLI 安裝 Config Sync，系統會預設啟用 RootSync 和 RepoSync API，且您無法停用。

後續步驟

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

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