排解 GKE 的受管理工作負載身分驗證問題

本文說明如何解決常見的代管工作負載身分錯誤。

如果 Google Kubernetes Engine (GKE) 工作負載 Pod 無法使用已掛接的憑證部署，請使用下列指令檢查 Pod 狀態：

kubectl describe pod POD_NAME -n POD_NAMESPACE

指令輸出內容包含 kubelet 和 gke-spiffe-controller 產生的 Pod 事件。查看這些事件的特定錯誤訊息，可能包括下列其中一項：

PermissionDenied 個錯誤

本節說明傳回 PermissionDenied RPC 錯誤代碼的錯誤。

PRIVATE_CA_AUTHORIZATION_FAILURE

這類錯誤訊息如下所示：

Permission denied while issuing the certificate: failed to issue the certificate from the GKE Auth: rpc error: code = PermissionDenied desc = Permission 'privateca.caPools.get' denied on resource 'privateca.googleapis.com/projects/CA_POOL_PROJECT_NUMBER/locations/REGION/caPools/CA_POOL_ID' (or it may not exist). Ensure that the CaPool exists and you have authorized the Managed Workload Identity to request certificates from the CaPool.

發生這項錯誤的原因是，workload identity pool 在從屬 CA 集區中缺少 CA Service Workload Certificate Requester 角色 (roles/privateca.workloadCertificateRequester)，或是 CA 集區不存在。

如要解決這項錯誤，請將角色授予集區：

gcloud privateca pools add-iam-policy-binding SUBORDINATE_CA_POOL_ID \
   --project=CA_POOL_PROJECT_ID \
   --location=REGION \
   --role=roles/privateca.workloadCertificateRequester \
   --member="principal://iam.googleapis.com/projects/WIP_PROJECT_NUMBER/name/locations/global/workloadIdentityPools/TRUST_DOMAIN_NAME"

更改下列內容：

  • SUBORDINATE_CA_POOL_ID：從屬 CA 集區 ID
  • CA_POOL_PROJECT_ID：CA 集區的專案 ID
  • REGION：從屬 CA 區域
  • WIP_PROJECT_NUMBER：Workload Identity Pool 專案的專案編號
  • TRUST_DOMAIN_NAME：信任網域的名稱。請根據集區類型，將名稱格式設為：
    • Google 管理的集區： PROJECT_ID.svc.id.goog
    • 自行管理的集區： POOL_NAME.global.POOL_HOST_PROJECT_NUMBER.workload.id.goog

WORKLOAD_IDENTITY_NOT_FOUND、WORKLOAD_POOL_NOT_FOUND 或 WORKLOAD_NAMESPACE_NOT_FOUND

這類錯誤訊息如下所示：

failed to issue the certificate from the GKE Auth: rpc error: code = PermissionDenied desc = Permission denied on resource 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_NAME/... (or it may not exist).

這項錯誤會對應至 WORKLOAD_IDENTITY_NOT_FOUND、WORKLOAD_POOL_NOT_FOUND 或 WORKLOAD_NAMESPACE_NOT_FOUND。如果工作負載身分集區、工作負載身分集區命名空間或受管理的身分資源不存在，或是遭到停用或刪除，就會發生這種情況。請注意，為避免洩漏資源不存在的資訊，這項錯誤會傳回 PermissionDenied，而非 NotFound。

如要解決這項錯誤，請在 IAM 中確認工作負載身分集區及其子資源是否存在，並檢查狀態。確認已正確設定，且未停用或刪除。

FailedPrecondition 個錯誤

本節說明傳回 FailedPrecondition RPC 錯誤代碼的錯誤，這通常表示設定缺漏或不正確。

WORKLOAD_IDENTITY_INVALID_CONFIGURATION

Pod 說明可能包含下列任一訊息：

failed to issue the certificate from the GKE Auth: rpc error: code = FailedPrecondition desc = There are no CaPools configured for certificate issuance. Ensure you have added certificate issuance configuration to the workload identity pool 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/WI_POOL_NAME', which contains at least one CaPool.

或

failed to issue the certificate from the GKE Auth: rpc error: code = FailedPrecondition desc = Missing Certificate issuance configuration in the Trust Domain. Ensure you have added certificate issuance configuration to the workload identity pool 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/WI_POOL_NAME' which contains at least one CaPool.

發生這項錯誤 (WORKLOAD_IDENTITY_INVALID_CONFIGURATION) 的原因，是 workload identity pool 未設定憑證核發設定 (CIC)，或設定的 CIC 未包含至少一個 CA 集區。

如要解決這項錯誤，請建立 CIC，其中至少包含一個 CA 集區，並使用該 CIC更新 workload identity pool。

CERTIFICATE_AUTHORITY_NOT_FOUND

這類錯誤訊息如下所示：

failed to issue the certificate from the GKE Auth: rpc error: code = FailedPrecondition desc = Failed to request certificates from the CaPool... There are no enabled CAs in the CaPool. Ensure that there is at least one enabled Certificate Authority to issue a certificate.

這個錯誤 (CERTIFICATE_AUTHORITY_NOT_FOUND) 表示在客戶設定的 CA 集區中，找不到可核發憑證的憑證授權單位。

如要解決這個錯誤，請確認設定的 CA 集區中存在憑證授權單位，且已啟用憑證核發功能。

CA_POOL_REGION_MISMATCH

這類錯誤訊息如下所示：

failed to issue the certificate from the GKE Auth: rpc error: code = FailedPrecondition desc = Unable to find a CaPool in the workload's region. Ensure you have setup a subordinate CaPool in 'WORKLOAD_REGION' and added it to the certificate issuance configuration of the Workload Identity Pool...

這項錯誤 (CA_POOL_REGION_MISMATCH) 表示工作負載的特定區域未設定任何 CA 集區。

如要解決這個錯誤，請在工作負載身分集區中，為工作負載的區域設定額外的 CA 集區，或是在已設定 CA 集區的區域中部署工作負載。

ResourceExhausted 個錯誤

本節說明傳回 ResourceExhausted RPC 錯誤代碼的錯誤。

PRIVATE_CA_QUOTA_EXCEEDED

這類錯誤訊息如下所示：

failed to issue the certificate from the GKE Auth: rpc error: code = ResourceExhausted desc = Quota exceeded for quota metric 'QUOTA_METRIC' and limit 'QUOTA_LIMIT' of service 'privateca.googleapis.com' for consumer 'project_number:PROJECT_NUMBER'.

如果您將工作負載身分集區設定為使用自訂 CA，但嘗試核發憑證時超出 CA 服務的配額或限制，就會發生這個錯誤 (PRIVATE_CA_QUOTA_EXCEEDED)。如果您使用 Google 代管的預設 CA，就不會發生這個錯誤。

  • QUOTA_METRIC 和 QUOTA_LIMIT：超出配額的具體指標和限制。例如 privateca.googleapis.com/enterprise_certificate_issuance 和 CertsPerEnterpriseCaPerMinute。

如要解決這項錯誤，請在 Google Cloud 控制台中查看 CA 服務配額和限制，並視需要申請提高配額。

InvalidArgument 個錯誤

本節說明傳回 InvalidArgument RPC 錯誤代碼的錯誤。

PRIVATE_CA_KEY_ALGORITHM_MISMATCH

這類錯誤訊息如下所示：

failed to issue the certificate from the GKE Auth: rpc error: code = InvalidArgument desc = Public key algorithm is not permitted by the CaPool's issuance policy. Ensure that the requested keyAlgorithm 'KEY_ALGO_IN_CSR' is permitted by the CAs in the CaPool 'privateca.googleapis.com/projects/PROJECT_NAME/locations/WORKLOAD_REGION/caPools/CA_POOL_NAME'.

這項錯誤 (PRIVATE_CA_KEY_ALGORITHM_MISMATCH) 表示憑證要求中指定的金鑰演算法與已設定 CA 集區的限制不相容。只有在憑證核發設定 (CIC) 中設定自訂金鑰演算法，並更新 workload identity pool 時，才會發生這種情況。

如要解決這個錯誤，請確認工作負載身分集區 CIC 中設定的演算法，與 CA 集區核發政策支援的演算法相容。

Unknown 個錯誤

本節說明傳回 Unknown RPC 錯誤代碼的錯誤。

UNKNOWN_PRIVATE_CA_CLIENT_ERROR

這類錯誤訊息如下所示：

failed to issue the certificate from the GKE Auth: rpc error: code = Unknown desc = Failed to get certificates using the CaPool... PRIVATE_CA_ERROR_MESSAGE

這項錯誤 (UNKNOWN_PRIVATE_CA_CLIENT_ERROR) 表示呼叫 CA 服務時發生不明的用戶端錯誤，例如提供給 API 的引數無效。

如要解決這項錯誤，請查看 CA Service API 傳回的特定錯誤訊息，找出無效引數或用戶端設定問題並加以修正。

信任套件傳播延遲

更新或輪替自行管理的 CA 時，更新內容大約需要 5 分鐘的傳播延遲時間，才會在「GKE 叢集」上生效。這是因為 gke-spiffe-controller 會每五分鐘檢查一次成員資格並擷取信任組合。

如果您使用 Google 代管的 CA，就不會發生這種延遲情形。

更新自行管理的 CA 時，請至少等待五分鐘，變更才會生效。