GKE Identity Service 診斷公用程式

GKE Identity Service 診斷公用程式可協助您排解以 FQDN 為基礎的驗證問題。如果您無法使用特定 OIDC 提供者驗證叢集，可以啟用這項工具，透過模擬 OIDC 提供者的登入流程，快速找出設定問題。

診斷公用程式僅適用於執行 GKE Enterprise 1.32 以上版本的個別叢集，且僅支援 OIDC。

啟用診斷公用程式

診斷公用程式預設為停用，必須先啟用才能用於疑難排解。如要啟用這項功能，請按照下列操作說明進行：

  1. 開啟 ClientConfig 自訂資源進行編輯：

    kubectl edit clientconfig default \
    --kubeconfig CLUSTER_KUBECONFIG -n kube-public

    資訊清單應如下所示：

    apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - name: oidc
    oidc:
      clientID: example-client-id
      clientSecret: example-client-secret
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      extraParams: prompt=consent, access_type=offline
      issuerURI: https://example.com
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: openid,email,offline_access
      userClaim: email

  2. 如以下範例所示，在 ClientConfig 資訊清單中新增 identityServiceOptions 區段，指定診斷公用程式設定：

    apiVersion: authentication.gke.io/v2alpha1
  kind: ClientConfig
  metadata:
    name: default
    namespace: kube-public
  spec:
    identityServiceOptions:
      diagnosticInterface:
        enabled: true
        expirationTime: TIMESTAMP
    authentication:
    - name: oidc
      oidc:
        clientID: example-client-id
        clientSecret: example-client-secret
        cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
        extraParams: prompt=consent, access_type=offline
        issuerURI: https://example.com
        kubectlRedirectURI: http://localhost:PORT/callback
        scopes: openid,email,offline_access
        userClaim: email

    將 TIMESTAMP 換成 RFC 3339 格式的到期時間。例如，2025-05-01T17:05:00Z。到期時間決定診斷公用程式功能自動關閉的時間。由於任何有叢集存取權的使用者都能使用診斷公用程式，因此適當設定到期時間有助於確保公用程式不會在不必要的情況下保持啟用狀態。設定到期時間時，建議設為未來 12 小時，但未來任何時間都有效。

  3. 儲存變更並結束文字編輯器，將資訊清單套用至叢集。

使用診斷公用程式模擬登入

啟用診斷公用程式後，您可以模擬登入事件，並取得相應的診斷資訊，用來排解特定供應商的問題。

  1. 在瀏覽器中前往下列網址，開啟診斷頁面：

    APISERVER-URL/diagnose

    將 APISERVER_URL 替換為叢集的完整網域名稱 (FQDN)。例如：https://apiserver.example.com。

    如果發生類似下列內容的禁止存取錯誤：

    forbidden: user \"system:anonymous\" cannot get path \"/diagnose\"

    將 :11001 的通訊埠號碼值附加至 APISERVER_URL。例如：https://apiserver.example.com:11001/diagnose。

    診斷頁面會顯示為叢集設定的 OIDC 提供者清單。

  2. 選取要排解問題的供應商。

  3. 照常登入。

    登入程序完成後，公用程式會顯示包含診斷資訊的頁面，協助您排解問題。

使用診斷頁面排解登入問題

診斷頁面會提供驗證摘要，並分為三個部分：

  • 狀態：包含 Success 或 Failed，視驗證是否成功而定。

  • 識別資訊提供者：包含用來登入的提供者詳細資料，例如 Name、Client ID 和 UserClaim。

  • ID 權杖：包含 GKE Identity Service 使用指定供應商擷取的 ID 權杖相關資訊。ID 權杖是包含一組鍵/值組合的 JSON 物件。金鑰可能包括 iss、aud、sub 和 email。

排解驗證成功問題

如果「狀態」部分顯示驗證成功，但您仍遇到問題，可能是因為缺少角色型存取控制 (RBAC)。如需其他疑難排解資訊，請參閱「RBACs for groups not working for OIDC providers」一文。

排解驗證失敗問題

如果「狀態」部分顯示驗證失敗，請先找出「身分識別提供者」和「ID 權杖」部分之間的不一致之處。

請檢查以下驗證規定：

  • 如果「身分識別提供者」中的 UserClaim 欄位為空白，則「ID 權杖」部分必須包含名為 sub 的欄位。如果缺少 sub 欄位，表示 ID 權杖有問題。

  • 「身分識別提供者」中的 UserClaim 欄位值必須是「ID 權杖」部分中的鍵。舉例來說，如果 UserClaim 欄位設為 email，則 ID 權杖中必須有名為 email 的欄位。

  • 「身分識別提供者」中的 GroupsClaim 欄位值必須是「ID 權杖」中的鍵。舉例來說，如果 GroupsClaim 欄位設為 groupsList (適用於支援群組的供應商)，則 ID 權杖中必須有 groupsList 欄位。

  • 「身分識別提供者」中的 Client ID 欄位值必須包含在「ID 權杖」部分中的 aud 欄位值內。

如果未滿足上述任一條件，請參閱下列指南，進一步瞭解如何使用 GKE Identity Service 正確設定叢集：

使用記錄檔進一步排解問題

GKE Identity Service Pod 記錄包含額外的偵錯資訊。如要使用 GKE Identity Service Pod 記錄：

  1. 啟用 GKE Identity Service 偵錯記錄。

  2. 檢查 GKE Identity Service 容器記錄。