Tetap teratur dengan koleksi
Simpan dan kategorikan konten berdasarkan preferensi Anda.
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:
Seperti yang ditunjukkan dalam contoh berikut, tambahkan bagian identityServiceOptions
ke manifes ClientConfig untuk menentukan konfigurasi
utilitas diagnostik:
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.
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.
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.
Pilih penyedia yang ingin Anda pecahkan masalahnya.
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:
[[["Mudah dipahami","easyToUnderstand","thumb-up"],["Memecahkan masalah saya","solvedMyProblem","thumb-up"],["Lainnya","otherUp","thumb-up"]],[["Sulit dipahami","hardToUnderstand","thumb-down"],["Informasi atau kode contoh salah","incorrectInformationOrSampleCode","thumb-down"],["Informasi/contoh yang saya butuhkan tidak ada","missingTheInformationSamplesINeed","thumb-down"],["Masalah terjemahan","translationIssue","thumb-down"],["Lainnya","otherDown","thumb-down"]],["Terakhir diperbarui pada 2025-09-01 UTC."],[],[],null,["# GKE Identity Service diagnostic utility\n=======================================\n\nThe GKE Identity Service diagnostic utility helps you to troubleshoot\n[FQDN-based authentication](/kubernetes-engine/enterprise/identity/setup/authenticate-fqdn-access)\nissues. If you're experiencing difficulties authenticating to a cluster using a\nspecific OIDC provider, you can enable the tool and use it to quickly identify\nconfiguration issues by simulating sign-in flows with\nyour OIDC provider.\n\nThe diagnostic utility is only available on [individual clusters](/kubernetes-engine/enterprise/identity/setup/per-cluster-overview)\nrunning GKE Enterprise 1.32 or higher and only supports OIDC.\n\nEnable the diagnostic utility\n-----------------------------\n\nThe diagnostic utility is disabled by default and must be enabled before you\ncan use it to troubleshoot. To enable it, use these instructions:\n\n1. Open the ClientConfig custom resource for editing:\n\n kubectl edit clientconfig default \\\n --kubeconfig \u003cvar translate=\"no\"\u003eCLUSTER_KUBECONFIG\u003c/var\u003e -n kube-public\n\n The manifest should look similar to the following: \n\n apiVersion: authentication.gke.io/v2alpha1\n kind: ClientConfig\n metadata:\n name: default\n namespace: kube-public\n spec:\n authentication:\n - name: oidc\n oidc:\n clientID: example-client-id\n clientSecret: example-client-secret\n cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc\n extraParams: prompt=consent, access_type=offline\n issuerURI: https://example.com\n kubectlRedirectURI: http://localhost:PORT/callback\n scopes: openid,email,offline_access\n userClaim: email\n\n2. As shown in the following example, add an `identityServiceOptions` section\n to the ClientConfig manifest to specify the diagnostic utility\n configuration:\n\n apiVersion: authentication.gke.io/v2alpha1\n kind: ClientConfig\n metadata:\n name: default\n namespace: kube-public\n spec:\n identityServiceOptions:\n diagnosticInterface:\n enabled: true\n expirationTime: \u003cvar translate=\"no\"\u003e\u003cspan class=\"devsite-syntax-l devsite-syntax-l-Scalar devsite-syntax-l-Scalar-Plain\"\u003eTIMESTAMP\u003c/span\u003e\u003c/var\u003e\n authentication:\n - name: oidc\n oidc:\n clientID: example-client-id\n clientSecret: example-client-secret\n cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc\n extraParams: prompt=consent, access_type=offline\n issuerURI: https://example.com\n kubectlRedirectURI: http://localhost:PORT/callback\n scopes: openid,email,offline_access\n userClaim: email\n\n Replace \u003cvar translate=\"no\"\u003eTIMESTAMP\u003c/var\u003e with an expiration time in\n [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format. For\n example, `2025-05-01T17:05:00Z`. The expiration time determines when the\n diagnostic utility feature automatically turns off. Since the diagnostic\n utility is available to anyone with cluster access, setting the expiration\n time appropriately helps ensure that the utility doesn't remain enabled\n longer than necessary. When setting the expiration time, it's recommended\n to set it to 12 hours in the future, although any time in the future is\n valid.\n3. Save your changes and exit the text editor to apply the manifest to the\n cluster.\n\nUse the diagnostic utility to simulate a sign-in\n------------------------------------------------\n\nOnce the diagnostic utility is enabled, you can simulate a sign-in event and get\nthe corresponding diagnostic information that you can use to troubleshoot issues\nwith a specific provider.\n\n1. Open the diagnostic page in a browser by navigating to the following URL:\n\n \u003cvar translate=\"no\"\u003eAPISERVER-URL\u003c/var\u003e/diagnose\n\n Replace \u003cvar translate=\"no\"\u003eAPISERVER_URL\u003c/var\u003e with the fully qualified domain\n name (FQDN) for your cluster. For example, `https://apiserver.example.com`.\n\n If you encounter a forbidden error, like the following: \n\n forbidden: user \\\"system:anonymous\\\" cannot get path \\\"/diagnose\\\"\n\n Append the port number value of **`:11001`** to the \u003cvar translate=\"no\"\u003eAPISERVER_URL\u003c/var\u003e. For example, `https://apiserver.example.com:11001/diagnose`.\n\n The diagnostic page displays a list of OIDC providers configured for your\n cluster.\n2. Select the provider that you want to troubleshoot.\n\n3. Sign in as usual.\n\n At the end of the sign in process, the utility displays a page with\n diagnostic information that can help you troubleshoot.\n\nUse the diagnostics page to troubleshoot sign-in problems\n---------------------------------------------------------\n\nThe diagnostics page provides an authentication summary, which is divided into\nthree sections:\n\n- **Status** : contains either `Success` or `Failed`, depending on whether the\n authentication has succeeded or not.\n\n- **Identity Provider** : contains details, such as `Name`, `Client ID`, and\n `UserClaim`, about the provider that was used to sign in.\n\n- **ID Token** : contains information about ID token fetched by\n GKE Identity Service using the given provider. The ID token is a JSON\n object containing a set of key-value pairs. Keys might include `iss`, `aud`,\n `sub`, and `email`.\n\n### Troubleshoot authentication success\n\nIf the content of the **Status** section indicates that the authentication has\nsucceeded and you're still experiencing issues, missing\nrole-based-access-controls (RBACs) might be the cause. For additional\ntroubleshooting information, see [RBACs for groups not working for OIDC\nproviders](/kubernetes-engine/enterprise/identity/setup/user-access-troubleshooting#rbacs_for_groups_not_working_for_oidc_providers)\nfor further troubleshooting.\n\n### Troubleshoot authentication failure\n\nIf the content of the **Status** section indicates that the authentication has\nfailed, start by looking for inconsistencies between the **Identity Provider**\nand **ID Token** sections.\n\nHere are a few authentication requirements that you should check:\n\n- If the `UserClaim` field in **Identity Provider** is empty, then the **ID\n Token** section must contain a field named `sub`. A missing `sub` field is\n an indication that there's a problem with the ID token.\n\n- The `UserClaim` field value in **Identity Provider** must be a key in the\n **ID Token** section. For example, if the `UserClaim` field is set to\n `email`, then there must be a field named `email` in **ID Token**.\n\n- The `GroupsClaim` field value in **Identity Provider** must be a key in **ID\n Token** . For example, if the `GroupsClaim` field is set to `groupsList` (for\n a provider that supports groups), then there must be a field named\n `groupsList` in **ID Token**.\n\n- The `Client ID` field value in **Identity Provider** must be contained\n within the value of the `aud` field in **ID Token** section.\n\nIf any of the preceding conditions aren't met, see one of the following guides\nfor more details on how to properly configure your clusters with\nGKE Identity Service:\n\n- If you set up GKE Identity Service for individual clusters, see the\n [instructions to configure individual\n clusters](/kubernetes-engine/enterprise/identity/setup/per-cluster#configure_clusters).\n\n- If you set up GKE Identity Service at a fleet level, see the\n [instructions to configure a fleet of\n clusters](/kubernetes-engine/enterprise/identity/setup/fleet-cluster#configure_clusters).\n\n### Use logs for further troubleshooting\n\nThe [GKE Identity Service pod\nlogs](/kubernetes-engine/enterprise/identity/setup/ais-pod-troubleshooting)\ncontain additional debugging information. To use GKE Identity Service pod\nlogs:\n\n1. [Enable the GKE Identity Service debug log](/kubernetes-engine/enterprise/identity/setup/user-access-troubleshooting#enable_the_debug_log).\n\n2. [Check the GKE Identity Service container log](/kubernetes-engine/enterprise/identity/setup/user-access-troubleshooting#check_the_container_log)."]]
