GKE Identity Service 診断ユーティリティ

GKE Identity Service 診断ユーティリティは、FQDN ベースの認証に関する問題のトラブルシューティングに役立ちます。特定の OIDC プロバイダを使用してクラスタを認証する際に問題が発生した場合は、このツールを有効にして、OIDC プロバイダでログインフローをシミュレートすることで、構成の問題をすばやく特定できます。

診断ユーティリティは、GKE Enterprise 1.32 以降を実行している個々のクラスタでのみ使用でき、OIDC のみをサポートします。

診断ユーティリティを有効にする

診断ユーティリティはデフォルトで無効になっているため、トラブルシューティングに使用する前に有効にする必要があります。有効にする手順は次のとおりです。

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

次の例のように、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 時間後に設定することをおすすめします。

変更を保存してテキストエディタを終了し、マニフェストをクラスタに適用します。

診断ユーティリティを有効にすると、ログインイベントをシミュレートして、特定のプロバイダに関する問題のトラブルシューティングに使用できる診断情報を取得できます。

次の URL に移動して、ブラウザで診断ページを開きます。
```
APISERVER-URL/diagnose
```
APISERVER_URL は、クラスタの完全修飾ドメイン名（FQDN）に置き換えます。たとえば、https://apiserver.example.com のようにします。

診断ページには、クラスタ用に構成された OIDC プロバイダのリストが表示されます。
トラブルシューティングするプロバイダを選択します。
通常どおりログインします。

ログインプロセスの最後に、トラブルシューティングに役立つ診断情報が表示されます。

診断ページを使用してログインの問題をトラブルシューティングする

診断ページには、認証の概要が表示されます。これは、次の 3 つのセクションに分かれています。

ステータス: 認証が成功したかどうかに応じて、Success または Failed が表示されます。
ID プロバイダ: ログインに使用されたプロバイダに関する詳細（Name、Client ID、UserClaim など）が表示されます。
ID トークン: 指定されたプロバイダを使用して GKE Identity Service が取得した ID トークンに関する情報が表示されます。ID トークンは、Key-Value ペアのセットを含む JSON オブジェクトです。キーには、iss、aud、sub、email などが含まれます。

認証成功のトラブルシューティング

[ステータス] セクションに認証の成功が示されていても問題が発生している場合は、ロールベースアクセス制御（RBAC）の不備が原因である可能性があります。トラブルシューティングの詳細については、OIDC プロバイダでグループの RBAC が機能しないをご覧ください。

認証エラーのトラブルシューティング

[ステータス] セクションに認証の失敗が示されている場合は、まず [ID プロバイダ] セクションと [ID トークン] セクションの不整合を探します。

確認すべき認証要件は次のとおりです。

[ID プロバイダ] の UserClaim フィールドが空の場合、[ID トークン] セクションに sub という名前のフィールドが含まれている必要があります。sub フィールドがない場合は、ID トークンに問題があります。
[ID プロバイダ] の UserClaim フィールドの値は、[ID トークン] セクションのキーと一致している必要があります。たとえば、UserClaim フィールドが email に設定されている場合、[ID トークン] に email という名前のフィールドが必要です。
[ID プロバイダ] の GroupsClaim フィールドの値は、[ID トークン] のキーと一致している必要があります。たとえば、GroupsClaim フィールドが groupsList（グループをサポートするプロバイダの場合）に設定されている場合、[ID トークン] に groupsList という名前のフィールドが必要です。
[ID プロバイダ] の Client ID フィールドの値は、[ID トークン] セクションの aud フィールドの値に含まれている必要があります。

上記の条件のいずれかが満たされていない場合は、次のいずれかのガイドで、GKE Identity Service を使用してクラスタを適切に構成する方法を確認してください。

個々のクラスタに GKE Identity Service を設定する場合は、個々のクラスタを構成する手順をご覧ください。
フリートレベルで GKE Identity Service を設定した場合は、クラスタのフリートを構成する手順をご覧ください。

ログを使用してトラブルシューティングを行う

GKE Identity Service Pod のログには、追加のデバッグ情報が含まれています。GKE Identity Service Pod のログを使用するには: