如要診斷及解決 Google Kubernetes Engine (GKE) 上常見的代管工作負載身分錯誤,請檢查 Pod 事件、workload identity pool、憑證核發設定和憑證授權單位服務資源。這些檢查可協助您解決 Pod 部署、X.509 憑證核發和憑證授權單位 (CA) 更新問題。
如果 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 集區 IDCA_POOL_PROJECT_ID:CA 集區的專案 IDREGION:從屬 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
- Google 代管集區:
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。如果 workload identity pool、workload identity pool 命名空間或受管理的身分資源不存在,或是已停用或刪除,就會發生這種情況。請注意,這項錯誤會傳回 PermissionDenied,而非 NotFound,以免洩漏資源不存在。
如要解決這項錯誤,請在 IAM 中確認 workload identity pool 及其子資源是否存在和狀態。請確認這些項目已正確設定,且未停用或刪除。
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 集區。
如要解決這項錯誤,請建立包含至少一個 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 集區。
如要解決這項錯誤,請在 workload identity pool 中,為工作負載所在區域設定額外的 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'.
如果將 workload identity pool 設為使用自訂 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 時,才會發生這種情況。
如要解決這個問題,請確認 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 後,請至少等待五分鐘,讓變更生效。