Utilitas diagnostik GKE Identity Service

Utilitas diagnostik Identity Service GKE membantu Anda memecahkan masalah autentikasi berbasis FQDN. Jika mengalami kesulitan saat mengautentikasi 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 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. Cara mengaktifkan utilitas ini bergantung pada cara Anda menyiapkan cluster dengan Identity Service GKE.

Penyiapan perangkat (konsol)

Jika Anda menggunakan konsolGoogle Cloud untuk menyiapkan cluster dengan Identity Service GKE di tingkat fleet, gunakan petunjuk ini.

  1. Buat file manifes ClientConfig YAML seperti yang diuraikan dalam Membuat file konfigurasi.

    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 untuk 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 menetapkan waktu habis masa berlaku, sebaiknya tetapkan ke 12 jam ke depan, meskipun waktu apa pun di masa mendatang valid.

  3. Selanjutnya, terapkan file ke cluster Anda dengan menjalankan:

    gcloud container fleet identity-service apply \
    --membership=CLUSTER_NAME \
    --config=MANIFEST_FILE_PATH

    Ganti kode berikut:

    • CLUSTER_NAME: nama unik cluster dalam fleet Anda.

    • MANIFEST_FILE_PATH: jalur file manifes ClientConfig YAML.

Penyiapan fleet (gcloud)

Jika Anda menggunakan Google Cloud CLI untuk menyiapkan cluster dengan Identity Service GKE di tingkat fleet, gunakan petunjuk ini:

  1. Buka file manifes ClientConfig yang dibuat saat Anda menyiapkan cluster dengan Identity Service GKE.

    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 untuk 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 menetapkan waktu habis masa berlaku, sebaiknya tetapkan ke 12 jam ke depan, meskipun waktu apa pun di masa mendatang valid.

  3. Selanjutnya, terapkan file ke cluster Anda dengan menjalankan:

    gcloud container fleet identity-service apply \
    --membership=CLUSTER_NAME \
    --config=MANIFEST_FILE_PATH

    Ganti kode berikut:

    • CLUSTER_NAME: nama unik cluster dalam fleet Anda.

    • MANIFEST_FILE_PATH: jalur file manifes ClientConfig YAML.

Penyiapan cluster individual

Jika Anda menyiapkan Identity Service GKE untuk setiap cluster, 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 untuk 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 menetapkan waktu habis masa berlaku, sebaiknya tetapkan 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 selesaikan masalahnya.

  3. Login seperti biasa.

    Di akhir proses login, utilitas akan 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.

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

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

Memecahkan masalah autentikasi berhasil

Jika konten bagian Status menunjukkan bahwa autentikasi telah berhasil dan Anda masih mengalami masalah, kontrol akses berbasis peran (RBAC) yang tidak ada mungkin menjadi penyebabnya. Untuk informasi pemecahan masalah tambahan, lihat RBAC untuk grup yang 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. Kolom sub yang tidak ada adalah indikasi bahwa ada masalah dengan token ID.

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

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

  • Nilai kolom Client ID di Identity Provider harus terdapat dalam nilai kolom aud di bagian ID Token.

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 Identity Service GKE berisi informasi proses debug tambahan. Untuk menggunakan log pod GKE Identity Service:

  1. Aktifkan log debug Identity Service GKE.

  2. Periksa log penampung GKE Identity Service.