Memecahkan masalah alat command line kubectl

Halaman ini menunjukkan cara menyelesaikan masalah pada alat command line kubectl saat Anda bekerja di Google Kubernetes Engine (GKE). Untuk saran yang lebih umum, lihat Pemecahan masalah kubectl dalam dokumentasi Kubernetes.

Error autentikasi dan otorisasi

Jika Anda mengalami error terkait autentikasi dan otorisasi saat menggunakan perintah alat command line kubectl, baca bagian berikut untuk mendapatkan saran.

Error: 401 (Tidak Sah)

Saat terhubung ke cluster GKE, Anda bisa mendapatkan error autentikasi dan otorisasi dengan kode status HTTP 401 (Unauthorized). Masalah ini mungkin terjadi saat Anda mencoba menjalankan perintah kubectl di cluster GKE dari lingkungan lokal. Untuk mempelajari lebih lanjut, lihat Masalah: Error autentikasi dan otorisasi.

Error: Cakupan autentikasi tidak memadai

Saat menjalankan gcloud container clusters get-credentials, Anda mungkin menerima error berikut:

ERROR: (gcloud.container.clusters.get-credentials) ResponseError: code=403, message=Request had insufficient authentication scopes.

Error ini terjadi karena Anda mencoba mengakses Kubernetes Engine API dari VM Compute Engine yang tidak memiliki cakupan cloud-platform.

Untuk mengatasi error ini, berikan cakupan cloud-platform yang hilang. Untuk mengetahui petunjuk tentang cara mengubah cakupan pada instance VM Compute Engine, lihat Membuat dan mengaktifkan akun layanan untuk instance dalam dokumentasi Compute Engine.

Error: gke-gcloud-auth-plugin yang dapat dieksekusi tidak ditemukan

Pesan error yang mirip dengan yang berikut ini dapat terjadi saat mencoba menjalankan perintah kubectl atau klien kustom yang berinteraksi dengan GKE:

Unable to connect to the server: getting credentials: exec: executable gke-gcloud-auth-plugin not found

It looks like you are trying to use a client-go credential plugin that is not installed.

To learn more about this feature, consult the documentation available at:
      https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins

Visit cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#install_plugin to install gke-gcloud-auth-plugin.

Unable to connect to the server: getting credentials: exec: fork/exec /usr/lib/google-cloud-sdk/bin/gke-gcloud-auth-plugin: no such file or directory

Untuk mengatasi masalah ini, instal gke-gcloud-auth-plugin seperti yang dijelaskan dalam Menginstal plugin yang diperlukan.

Error: Penyedia autentikasi tidak ditemukan

Error berikut terjadi jika kubectl atau klien Kubernetes kustom telah di-build dengan Kubernetes client-go versi 1.26 atau yang lebih baru:

no Auth Provider found for name "gcp"

Untuk mengatasi masalah ini, selesaikan beberapa langkah berikut:

  1. Instal gke-gcloud-auth-plugin seperti yang dijelaskan dalam Menginstal plugin yang diperlukan.

  2. Update gcloud CLI ke versi terbaru:

    gcloud components update

  3. Update file kubeconfig:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --region=COMPUTE_REGION

    Ganti kode berikut:

    • CLUSTER_NAME: nama cluster Anda.
    • COMPUTE_REGION: region Compute Engine untuk cluster Anda. Untuk cluster zona, gunakan --zone=COMPUTE_ZONE.

Error: Plugin auth gcp tidak digunakan lagi, gunakan gcloud sebagai gantinya

Anda mungkin melihat pesan peringatan berikut setelah menginstal gke-gcloud-auth-plugin dan menjalankan perintah kubectl terhadap cluster GKE:

WARNING: the gcp auth plugin is deprecated in v1.22+, unavailable in v1.25+; use gcloud instead.

Pesan ini muncul jika versi klien Anda lebih lama dari 1.26.

Untuk mengatasi masalah ini, beri tahu klien Anda agar menggunakan plugin autentikasi gke-gcloud-auth-plugin:

  1. Buka skrip login shell Anda di editor teks:

    Bash

    vi ~/.bashrc

    Zsh

    vi ~/.zshrc

    Jika Anda menggunakan PowerShell, lewati langkah ini.

  2. Tetapkan variabel lingkungan berikut:

    Bash

    export USE_GKE_GCLOUD_AUTH_PLUGIN=True

    Zsh

    export USE_GKE_GCLOUD_AUTH_PLUGIN=True

    PowerShell

    [Environment]::SetEnvironmentVariable('USE_GKE_GCLOUD_AUTH_PLUGIN', True, 'Machine')

  3. Terapkan variabel di lingkungan Anda:

    Bash

    source ~/.bashrc

    Zsh

    source ~/.zshrc

    PowerShell

    Keluar dari terminal dan buka sesi terminal baru.

  4. Update gcloud CLI:

    gcloud components update

  5. Lakukan autentikasi ke cluster Anda:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --region=COMPUTE_REGION

    Ganti kode berikut:

    • CLUSTER_NAME: nama cluster Anda.
    • COMPUTE_REGION: region Compute Engine untuk cluster Anda. Untuk cluster zona, gunakan --zone=COMPUTE_ZONE.

Masalah: Perintah kubectl tidak ditemukan

Jika Anda menerima pesan bahwa perintah kubectl tidak ditemukan, instal ulang biner kubectl dan tetapkan variabel lingkungan $PATH:

  1. Instal biner kubectl:

    gcloud components update kubectl

  2. Saat penginstal meminta Anda untuk mengubah variabel lingkungan $PATH, masukkan y untuk melanjutkan. Dengan mengubah variabel ini, Anda dapat menggunakan perintah kubectl tanpa mengetik jalur lengkapnya.

    Atau, tambahkan baris berikut ke tempat shell Anda menyimpan variabel lingkungan, seperti ~/.bashrc (atau ~/.bash_profile di macOS):

    export PATH=$PATH:/usr/local/share/google/google-cloud-sdk/bin/

  3. Jalankan perintah berikut untuk memuat file yang telah diperbarui. Contoh berikut menggunakan .bashrc:

    source ~/.bashrc

    Jika Anda menggunakan macOS, gunakan ~/.bash_profile, bukan .bashrc.

Masalah: Perintah kubectl menampilkan error "koneksi ditolak"

Jika perintah kubectl menampilkan error "koneksi ditolak", Anda harus menetapkan konteks cluster dengan perintah berikut:

gcloud container clusters get-credentials CLUSTER_NAME

Ganti CLUSTER_NAME dengan nama cluster Anda. Jika Anda tidak yakin dengan apa yang harus dimasukkan untuk nama cluster, gunakan perintah berikut untuk melihat daftar cluster Anda:

gcloud container clusters list

Error: Waktu perintah kubectl habis

Jika Anda membuat cluster dan mencoba menjalankan perintah kubectl terhadap cluster, tetapi waktu tunggu perintah kubectl habis, Anda akan melihat error yang mirip dengan berikut:

  • Unable to connect to the server: dial tcp IP_ADDRESS: connect: connection timed out
  • Unable to connect to the server: dial tcp IP_ADDRESS: i/o timeout.

Error ini menunjukkan bahwa kubectl tidak dapat berkomunikasi dengan bidang kontrol cluster.

Untuk mengatasi masalah ini, verifikasi dan tetapkan konteks tempat cluster ditetapkan dan pastikan konektivitas ke cluster:

  1. Buka $HOME/.kube/config atau jalankan perintah kubectl config view untuk memverifikasi bahwa file konfigurasi berisi konteks cluster dan alamat IP eksternal panel kontrol.

  2. Tetapkan kredensial cluster:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=COMPUTE_LOCATION \
    --project=PROJECT_ID

    Ganti kode berikut:

    • CLUSTER_NAME: nama cluster Anda.
    • COMPUTE_LOCATION: Lokasi Compute Engine.
    • PROJECT_ID: ID project tempat cluster dibuat.

  3. Jika Anda telah mengaktifkan jaringan yang diizinkan di cluster, pastikan daftar jaringan yang diizinkan yang ada menyertakan IP keluar dari mesin tempat Anda mencoba membuat koneksi. Anda dapat menemukan jaringan yang diizinkan di konsol atau dengan menjalankan perintah berikut:

    gcloud container clusters describe CLUSTER_NAME \
    --location=COMPUTE_LOCATION \
    --project=PROJECT_ID \
    --format "flattened(controlPlaneEndpointsConfig.ipEndpointsConfig.authorizedNetwork
sConfig.cidrBlocks[])"

    Jika IP keluar mesin tidak disertakan dalam daftar jaringan yang diizinkan dari output perintah sebelumnya, selesaikan salah satu langkah berikut:

Error: Perintah kubectl menampilkan gagal menegosiasikan versi API

Jika perintah kubectl menampilkan error failed to negotiate an API version, Anda harus memastikan kubectl memiliki kredensial autentikasi:

gcloud auth application-default login

Masalah: Perintah kubectl logs, attach, exec, atau port-forward berhenti merespons

Jika perintah kubectl logs, attach, exec, atau port-forward berhenti merespons, biasanya server API tidak dapat berkomunikasi dengan node.

Pertama, periksa apakah cluster Anda memiliki node. Jika Anda telah memperkecil skala node dalam cluster menjadi nol, perintah ini tidak akan berfungsi. Untuk mengatasi masalah ini, ubah ukuran cluster agar memiliki setidaknya satu node.

Jika cluster Anda memiliki minimal satu node, periksa apakah Anda menggunakan tunnel SSH atau proxy Konnectivity untuk mengaktifkan komunikasi yang aman. Bagian berikut membahas langkah-langkah pemecahan masalah khusus untuk setiap layanan:

Memecahkan masalah SSH

Jika Anda menggunakan SSH, GKE akan menyimpan file kunci publik SSH di metadata project Compute Engine. Semua VM Compute Engine yang menggunakan image yang disediakan Google akan secara berkala memeriksa metadata umum project mereka dan metadata instance-nya untuk mencari kunci SSH yang akan ditambahkan ke daftar pengguna yang diizinkan dalam VM tersebut. GKE juga menambahkan aturan firewall ke jaringan Compute Engine Anda untuk mengizinkan akses SSH dari alamat IP panel kontrol ke setiap node dalam cluster.

Setelan berikut dapat menyebabkan masalah pada komunikasi SSH:

  • Aturan firewall jaringan Anda tidak mengizinkan akses SSH dari panel kontrol.

    Semua jaringan Compute Engine dibuat dengan aturan firewall bernama default-allow-ssh yang mengizinkan akses SSH dari semua alamat IP (tentunya memerlukan kunci pribadi yang valid). GKE juga menyisipkan aturan SSH untuk setiap cluster publik berformat gke-CLUSTER_NAME-RANDOM_CHARACTERS-ssh yang mengizinkan akses SSH secara khusus dari panel kontrol cluster ke node cluster.

    Jika kedua aturan ini tidak ada, maka panel kontrol tidak dapat membuka tunnel SSH.

    Untuk memverifikasi bahwa ini adalah penyebab masalahnya, periksa apakah konfigurasi Anda memiliki aturan ini.

    Untuk mengatasi masalah ini, identifikasi tag yang ada di semua node cluster, lalu tambahkan kembali aturan firewall yang mengizinkan akses ke VM dengan tag tersebut dari alamat IP panel kontrol.

  • Entri metadata umum project Anda untuk ssh-keys sudah penuh.

    Jika entri metadata project yang bernama ssh-keys hampir mencapai batas ukuran maksimum, GKE tidak dapat menambahkan kunci SSH-nya sendiri untuk membuka tunnel SSH.

    Untuk memverifikasi bahwa ini adalah masalahnya, periksa panjang daftar ssh-keys. Anda dapat melihat metadata project dengan menjalankan perintah berikut, secara opsional menyertakan flag --project:

    gcloud compute project-info describe [--project=PROJECT_ID]

    Untuk mengatasi masalah ini, hapus beberapa kunci SSH yang tidak diperlukan lagi.

  • Anda telah menetapkan kolom metadata dengan kunci ssh-keys pada VM di cluster.

    Agen node pada VM lebih memilih kunci SSH per instance dibandingkan kunci SSH di seluruh project. Jadi, jika Anda telah menetapkan kunci SSH secara khusus pada node cluster, maka kunci SSH panel kontrol dalam metadata project akan diabaikan oleh node.

    Untuk memverifikasi bahwa ini adalah masalahnya, jalankan gcloud compute instances describe VM_NAME dan cari kolom ssh-keys di metadata.

    Untuk mengatasi masalah ini, hapus kunci SSH per instance dari metadata instance.

Memecahkan masalah proxy Konnectivity

Anda dapat menentukan apakah cluster menggunakan proxy Konnectivity dengan memeriksa Deployment sistem berikut:

kubectl get deployments konnectivity-agent --namespace kube-system

Jika cluster Anda menggunakan proxy Konnectivity, outputnya akan mirip dengan berikut:

NAME                 READY   UP-TO-DATE   AVAILABLE   AGE
konnectivity-agent   3/3     3            3           18d

Setelah memastikan bahwa Anda menggunakan proxy Konnectivity, pastikan agen Konnectivity memiliki akses firewall yang diperlukan dan kebijakan jaringan Anda disiapkan dengan benar.

Mengizinkan akses firewall yang diperlukan

Pastikan aturan firewall jaringan Anda mengizinkan akses ke port berikut:

  • Port bidang kontrol: Saat pembuatan cluster, agen Konnectivity membuat koneksi ke bidang kontrol pada port 8132. Saat Anda menjalankan perintah kubectl, server API akan menggunakan koneksi ini untuk berkomunikasi dengan cluster. Pastikan Anda mengizinkan traffic Keluar ke platform kontrol cluster pada port 8132 (untuk perbandingan, server API menggunakan 443). Jika memiliki aturan yang menolak akses keluar, Anda mungkin perlu mengubah aturan atau membuat pengecualian.

  • Port kubelet: Karena agen Konnectivity adalah Pod sistem yang di-deploy di node cluster, pastikan aturan firewall Anda mengizinkan jenis traffic berikut:

    • Traffic masuk ke workload Anda di port 10250 dari rentang Pod Anda.
    • Traffic keluar dari rentang Pod Anda.

    Jika aturan firewall Anda tidak mengizinkan jenis traffic ini, ubah aturan Anda.

Menyesuaikan kebijakan jaringan

Jika kebijakan jaringan cluster Anda memblokir traffic masuk dari namespace kube-system ke namespace workload, hal ini dapat menyebabkan masalah pada proxy Konnectivity.

Fitur ini tidak diperlukan agar cluster berfungsi dengan benar. Jika Anda memilih untuk terus mengunci jaringan cluster dari semua akses eksternal, perlu diketahui bahwa fitur seperti ini tidak akan berfungsi.

Untuk memverifikasi bahwa ini adalah penyebab masalahnya, temukan kebijakan jaringan di namespace yang terpengaruh dengan menjalankan perintah berikut:

kubectl get networkpolicy --namespace AFFECTED_NAMESPACE

Untuk mengatasi masalah ini, tambahkan hal berikut ke kolom spec.ingress kebijakan jaringan:

- from:
  - namespaceSelector:
      matchLabels:
        kubernetes.io/metadata.name: kube-system
    podSelector:
      matchLabels:
        k8s-app: konnectivity-agent

Langkah selanjutnya

Jika Anda memerlukan bantuan tambahan, hubungi Cloud Customer Care.