Menginstal kubectl dan mengonfigurasi akses cluster

Halaman ini menjelaskan cara menginstal dan mengonfigurasi alat command line kubectl untuk berinteraksi dengan cluster Google Kubernetes Engine (GKE) Anda.

Ringkasan

kubectl adalah alat command line yang dapat Anda gunakan untuk berinteraksi dengan cluster GKE. Untuk menggunakan kubectl dengan GKE, Anda harus menginstal dan mengonfigurasinya agar dapat berkomunikasi dengan cluster Anda. Konfigurasi kubectl lebih lanjut diperlukan jika Anda menjalankan beberapa cluster di Google Cloud.

Halaman ini menampilkan hal berikut:

• Cara kerja kubectl
• Cara menginstal kubectl dan dependensi yang diperlukan.
• Cara menetapkan cluster default untuk kubectl.
• Cara menjalankan perintah kubectl terhadap cluster tertentu.

Sebelum memulai

Sebelum memulai, pastikan Anda telah menjalankan tugas berikut:

• Aktifkan Google Kubernetes Engine API.
Aktifkan Google Kubernetes Engine API
• Jika ingin menggunakan Google Cloud CLI untuk tugas ini, instal lalu initialize gcloud CLI. Jika sebelumnya Anda telah menginstal gcloud CLI, dapatkan versi terbaru dengan menjalankan gcloud components update.

Instal kubectl

Anda dapat menginstal kubectl menggunakan Google Cloud CLI atau pengelola paket eksternal seperti apt atau yum.

Menginstal plugin yang diperlukan

kubectl dan klien Kubernetes lainnya memerlukan plugin autentikasi, gke-gcloud-auth-plugin, yang menggunakan framework Plugin Kredensial Client-go untuk memberikan token autentikasi agar dapat berkomunikasi dengan cluster GKE.

Sebelum Kubernetes versi 1.26 dirilis, gcloud CLI akan mulai mewajibkan biner gke-gcloud-auth-plugin untuk diinstal. Jika tidak diinstal, penginstalan kubectl yang ada atau klien Kubernetes kustom lainnya akan berhenti berfungsi.

Anda harus menginstal plugin ini untuk menggunakan kubectl dan klien lain agar dapat berinteraksi dengan GKE. Klien yang ada akan menampilkan pesan error jika plugin tidak diinstal.

Sebelum memulai, periksa apakah plugin sudah terinstal:

gke-gcloud-auth-plugin --version

Jika output menampilkan informasi versi, lewati bagian ini.

Anda dapat menginstal plugin autentikasi menggunakan gcloud CLI atau pengelola paket eksternal seperti apt atau yum.

  gcloud components install gke-gcloud-auth-plugin

  apt-get install google-cloud-sdk-gke-gcloud-auth-plugin

  yum install google-cloud-sdk-gke-gcloud-auth-plugin

Verifikasi penginstalan biner gke-gcloud-auth-plugin:

1. Periksa versi biner gke-gcloud-auth-plugin:

   gke-gcloud-auth-plugin --version
   

2. Update konfigurasi kubectl untuk menggunakan plugin:

   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.

3. Verifikasi konfigurasi:

   kubectl get namespaces
   

   Outputnya mirip dengan hal berikut ini:

   NAME              STATUS   AGE
   default           Active   51d
   kube-node-lease   Active   51d
   kube-public       Active   51d
   kube-system       Active   51d
   

Untuk informasi selengkapnya tentang alasan diperlukannya plugin ini, lihat Kubernetes KEP.

Berinteraksi dengan kubectl

Kubernetes menggunakan file YAML bernama kubeconfig guna menyimpan informasi autentikasi cluster untuk kubectl. Secara default, file disimpan di $HOME/.kube/config.

kubeconfig berisi grup parameter akses yang disebut konteks. Setiap konteks berisi cluster Kubernetes, pengguna, dan namespace default opsional. kubectl merujuk pada konteks saat menjalankan perintah.

Berikut adalah tugas yang dapat Anda selesaikan untuk mengonfigurasi kubectl:

• Pilih cluster mana yang akan dihubungi kubectl.
• Tetapkan cluster default untuk kubectl dengan menyetel konteks saat ini di file kubeconfig.
• Jalankan perintah kubectl terhadap cluster tertentu menggunakan flag --cluster.

Lihat kubeconfig

Untuk melihat kubeconfig lingkungan Anda, jalankan perintah berikut:

kubectl config view

Perintah ini menampilkan daftar semua cluster dengan entri kubeconfig yang telah dibuat. Jika cluster GKE tercantum, Anda dapat menjalankan perintah kubectl untuknya di lingkungan Anda saat ini. Jika tidak, Anda perlu Menyimpan informasi cluster untuk kubectl.

Lihat konteks saat ini untuk kubectl

Konteks saat ini adalah cluster yang saat ini menjadi default untuk kubectl. Semua perintah kubectl dijalankan pada cluster tersebut.

Saat Anda membuat cluster menggunakan gcloud container clusters create-auto, entri akan otomatis ditambahkan ke file kubeconfig di lingkungan Anda, dan konteks saat ini akan berubah pada cluster tersebut. Contoh:

gcloud container clusters create-auto my-cluster
Creating my-cluster...done
Fetching cluster endpoint and auth data.
kubeconfig entry generated for my-cluster

Guna melihat konteks saat ini untuk kubectl, jalankan perintah berikut:

kubectl config current-context

Simpan informasi cluster untuk kubectl

Saat Anda membuat cluster menggunakan Google Cloud Console atau menggunakan gcloud CLI dari komputer lain, file kubeconfig lingkungan Anda tidak akan diperbarui. Selain itu, jika anggota tim project menggunakan gcloud CLI untuk membuat cluster dari komputer mereka, kubeconfig mereka akan diupdate, tetapi milik Anda tidak. Entri kubeconfig berisi:

• Kredensial Anda seperti yang ditampilkan dalam gcloud auth list, atau
• Kredensial default aplikasi, jika dikonfigurasi.

Untuk membuat konteks kubeconfig di lingkungan Anda, pastikan Anda memiliki izin container.clusters.get. Peran IAM dengan hak istimewa paling rendah yang memberikan izin ini adalah container.clusterViewer.

Untuk menghasilkan konteks kubeconfig bagi cluster tertentu, jalankan perintah berikut:

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

Ganti kode berikut:

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

Membuat entri kubeconfig menggunakan alamat IP internal cluster pribadi

Semua cluster memiliki endpoint kanonis. Endpoint ini mengekspos server Kubernetes API yang digunakan kubectl dan layanan lainnya untuk berkomunikasi dengan bidang kontrol cluster Anda.

Cluster pribadi memiliki dua alamat IP endpoint yang terpisah: privateEndpoint, yang merupakan alamat IP internal, dan publicEndpoint, yang merupakan alamat IP eksternal eksternal. Kolom endpoint mengacu pada alamat IP eksternal, kecuali jika akses publik ke endpoint dinonaktifkan, dalam hal ini alamat IP pribadi akan digunakan.

Untuk cluster pribadi, jika Anda lebih suka menggunakan alamat IP internal sebagai endpoint, jalankan perintah berikut:

gcloud container clusters get-credentials CLUSTER_NAME --internal-ip

Ganti CLUSTER_NAME dengan nama cluster Anda.

Menjalankan get-credentials akan menggunakan alamat IP yang ditentukan di kolom endpoint secara default.

Menetapkan cluster default untuk perintah kubectl

Jika sebelumnya Anda telah membuat entri kubeconfig untuk cluster, Anda dapat mengalihkan konteks saat ini untuk kubectl ke cluster tersebut dengan menjalankan perintah berikut:

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.

Misalnya, pertimbangkan project dengan dua cluster, my-cluster dan my-new-cluster. Konteks saat ini adalah my-new-cluster, tetapi Anda ingin menjalankan semua perintah kubectl terhadap my-cluster. Untuk mengalihkan konteks saat ini dari my-new-cluster ke my-cluster, jalankan perintah berikut:

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

Menjalankan perintah kubectl individu terhadap cluster tertentu

Anda dapat menjalankan perintah kubectl satu per satu terhadap cluster tertentu menggunakan --cluster=CLUSTER_NAME.

Misalnya, pertimbangkan lingkungan dengan dua cluster, my-cluster dan my-new-cluster, dengan konteks saat ini adalah my-cluster. Anda ingin men-deploy aplikasi ke my-new-cluster, tetapi tidak ingin mengubah konteks saat ini. Untuk men-deploy aplikasi ke my-new-cluster tanpa mengubah konteks saat ini, Anda harus menjalankan perintah berikut:

kubectl run my-app --image us-docker.pkg.dev/my-project/my-repo/my-app:1.0 --cluster my-new-cluster

Pemecahan masalah

Untuk pemecahan masalah lainnya, lihat Memecahkan masalah umum.

Cakupan autentikasi tidak memadai

Saat menjalankan gcloud container clusters get-credentials, Anda akan 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 mengetahui petunjuk tentang cara mengubah cakupan pada instance VM Compute Engine, lihat Membuat dan mengaktifkan akun layanan untuk instance.

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

Jika error berikut diterima saat mencoba menjalankan kubectl atau klien kustom yang berinteraksi dengan GKE, instal gke-gcloud-auth-plugin seperti yang dijelaskan dalam Petunjuk penginstalan. Pesan error mirip dengan yang berikut ini:

• Contoh error

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.

• Contoh error

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

ERROR: panic: no Auth Provider found for name gcp

Error no Auth Provider found for name "gcp" diterima jika kubectl atau klien Kubernetes kustom telah dibuat dengan Kubernetes client-go versi 1.26 atau yang lebih baru, seperti yang dijelaskan dalam Cara kerjanya. Hal ini dapat diatasi dengan langkah-langkah berikut:

1. Instal gke-gcloud-auth-plugin seperti yang dijelaskan dalam Petunjuk penginstalan.

2. Update gcloud CLI ke versi terbaru menggunakan gcloud components update.

3. Perbarui 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.

PERINGATAN: plugin auth gcp tidak digunakan lagi, gunakan gcloud sebagai gantinya

Anda mungkin melihat pesan peringatan ini setelah menginstal gke-gcloud-auth-plugin dan menjalankan perintah kubectl terhadap cluster GKE. Pesan ini muncul jika versi klien Anda lebih lama dari 1.26.

Untuk memberi tahu klien Anda agar menggunakan plugin autentikasi gke-gcloud-auth-plugin, lakukan hal berikut:

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.

Langkah selanjutnya

• Pelajari cara mengizinkan akses ke resource di cluster GKE.
• Melakukan autentikasi ke layanan Google Cloud dari workload GKE.
• Baca tips praktis kubectl.