Utilitas diagnostik GKE Identity Service

Utilitas diagnostik GKE Identity Service membantu Anda memecahkan masalah autentikasi berbasis FQDN. Jika mengalami kesulitan melakukan autentikasi ke cluster menggunakan penyedia OIDC tertentu, Anda dapat mengaktifkan alat ini dan menggunakannya untuk mengidentifikasi masalah konfigurasi dengan cepat dengan menyimulasikan alur login dengan penyedia OIDC Anda.

Utilitas diagnostik hanya tersedia di setiap cluster yang menjalankan GKE Enterprise 1.32 atau yang lebih tinggi dan hanya mendukung OIDC.

Mengaktifkan utilitas diagnostik

Utilitas diagnostik dinonaktifkan secara default dan harus diaktifkan sebelum Anda dapat menggunakannya untuk memecahkan masalah. Untuk mengaktifkannya, gunakan petunjuk berikut:

  1. Buka resource kustom ClientConfig untuk mengedit:

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

    Manifes akan terlihat seperti berikut:

    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. Seperti yang ditunjukkan dalam contoh berikut, tambahkan bagian identityServiceOptions ke manifes ClientConfig untuk menentukan konfigurasi utilitas diagnostik:

    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

    Ganti TIMESTAMP dengan waktu habis masa berlaku dalam format RFC 3339. Contohnya, 2025-05-01T17:05:00Z. Waktu habis masa berlaku menentukan kapan fitur utilitas diagnostik otomatis dinonaktifkan. Karena utilitas diagnostik tersedia bagi siapa saja yang memiliki akses cluster, menetapkan waktu habis masa berlaku dengan tepat akan membantu memastikan bahwa utilitas tidak tetap diaktifkan lebih lama dari yang diperlukan. Saat menyetel waktu habis masa berlaku, sebaiknya setel ke 12 jam ke depan, meskipun waktu apa pun di masa mendatang valid.

  3. Simpan perubahan Anda dan keluar dari editor teks untuk menerapkan manifes ke cluster.

Menggunakan utilitas diagnostik untuk menyimulasikan login

Setelah utilitas diagnostik diaktifkan, Anda dapat menyimulasikan peristiwa login dan mendapatkan informasi diagnostik yang sesuai yang dapat Anda gunakan untuk memecahkan masalah dengan penyedia tertentu.

  1. Buka halaman diagnostik di browser dengan membuka URL berikut:

    APISERVER-URL/diagnose

    Ganti APISERVER_URL dengan nama domain yang sepenuhnya memenuhi syarat (FQDN) untuk cluster Anda. Contoh, https://apiserver.example.com.

    Halaman diagnostik menampilkan daftar penyedia OIDC yang dikonfigurasi untuk cluster Anda.

  2. Pilih penyedia yang ingin Anda pecahkan masalahnya.

  3. Login seperti biasa.

    Di akhir proses login, utilitas menampilkan halaman dengan informasi diagnostik yang dapat membantu Anda memecahkan masalah.

Menggunakan halaman diagnostik untuk memecahkan masalah login

Halaman diagnostik memberikan ringkasan autentikasi, yang dibagi menjadi tiga bagian:

  • Status: berisi Success atau Failed, bergantung pada apakah autentikasi berhasil atau tidak.

  • Penyedia Identitas: berisi detail, seperti Name, Client ID, dan UserClaim, tentang penyedia yang digunakan untuk login.

  • Token ID: berisi informasi tentang token ID yang diambil oleh GKE Identity Service menggunakan penyedia yang diberikan. Token ID adalah objek JSON yang berisi serangkaian key-value pair. Kunci dapat mencakup iss, aud, sub, dan email.

Memecahkan masalah keberhasilan autentikasi

Jika konten bagian Status menunjukkan bahwa autentikasi telah berhasil dan Anda masih mengalami masalah, penyebabnya mungkin adalah role-based-access-controls (RBAC) yang tidak ada. Untuk mengetahui informasi pemecahan masalah tambahan, lihat RBAC untuk grup tidak berfungsi untuk penyedia OIDC untuk pemecahan masalah lebih lanjut.

Memecahkan masalah kegagalan autentikasi

Jika konten bagian Status menunjukkan bahwa autentikasi telah gagal, mulailah dengan mencari inkonsistensi antara bagian Penyedia Identitas dan Token ID.

Berikut beberapa persyaratan autentikasi yang harus Anda periksa:

  • Jika kolom UserClaim di Identity Provider kosong, bagian ID Token harus berisi kolom bernama sub. Tidak adanya kolom sub menunjukkan bahwa ada masalah dengan token ID.

  • Nilai kolom UserClaim di Identity Provider harus berupa kunci di bagian ID Token. Misalnya, jika kolom UserClaim disetel ke email, maka harus ada kolom bernama email di Token ID.

  • Nilai kolom GroupsClaim di Identity Provider harus berupa kunci di ID Token. Misalnya, jika kolom GroupsClaim disetel ke groupsList (untuk penyedia yang mendukung grup), maka harus ada kolom bernama groupsList di Token ID.

  • Nilai kolom Client ID di Penyedia Identitas harus ada dalam nilai kolom aud di bagian Token ID.

Jika salah satu kondisi sebelumnya tidak terpenuhi, lihat salah satu panduan berikut untuk mengetahui detail selengkapnya tentang cara mengonfigurasi cluster dengan benar menggunakan Layanan Identitas GKE:

Menggunakan log untuk pemecahan masalah lebih lanjut

Log pod GKE Identity Service berisi informasi debug tambahan. Untuk menggunakan log pod GKE Identity Service:

  1. Aktifkan log debug GKE Identity Service.

  2. Periksa log container GKE Identity Service.