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

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

缺少讀者存取權

使用 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。詳情請參閱「註冊叢集」。如果叢集所在的專案與 Fleet 主機專案不同，您需要在 Fleet 主機專案中，將 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 值區中。將 OCI 映像檔或 Helm 圖表存取權授予 Artifact Registry 中的 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，且無法停用。

後續步驟

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

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