Menggunakan gateway Connect

Halaman ini memberi tahu Anda cara menggunakan gateway Connect untuk terhubung ke cluster terdaftar. Sebelum membaca panduan ini, Anda harus memahami konsep dalam ringkasan kami. Panduan ini mengasumsikan bahwa administrator project Anda telah menyiapkan gateway, dan memberi Anda peran dan izin yang diperlukan.

Sebelum memulai

• Pastikan Anda telah menginstal alat command line berikut:

  • Google Cloud CLI versi terbaru, alat command line untuk berinteraksi dengan Google Cloud.
  • kubectl

  Jika Anda menggunakan Cloud Shell sebagai lingkungan shell untuk berinteraksi dengan Google Cloud, alat ini akan diinstal untuk Anda.

• Pastikan Anda telah melakukan inisialisasi gcloud CLI untuk digunakan dengan project Anda.

Login ke akun Google Cloud Anda

Anda dapat menggunakan akun Google Cloud Anda sendiri atau akun layanan Google Cloud untuk berinteraksi dengan cluster yang terhubung melalui gateway API.

Ikuti petunjuk di Memberi otorisasi pada alat Google Cloud CLI untuk login ke akun pengguna Anda. Gateway Connect mendukung peniruan akun layanan, sehingga meskipun Anda login ke akun pengguna Anda sendiri, Anda dapat menggunakan akun layanan untuk berinteraksi dengan cluster, seperti yang akan Anda lihat di bagian berikut.

Memilih cluster terdaftar

Jika tidak mengetahui nama cluster yang ingin diakses, Anda dapat melihat semua cluster terdaftar di fleet saat ini dengan menjalankan perintah berikut:

gcloud container fleet memberships list

Halaman ini mencantumkan semua cluster fleet Anda, termasuk nama keanggotaan dan ID eksternalnya. Setiap cluster dalam fleet memiliki nama keanggotaan yang unik. Untuk cluster GKE, nama keanggotaan umumnya cocok dengan nama yang Anda berikan saat membuat cluster, kecuali jika nama cluster tidak unik dalam project-nya saat pendaftaran.

Mendapatkan gateway cluster kubeconfig

Gunakan perintah berikut untuk mendapatkan kubeconfig yang diperlukan untuk berinteraksi dengan cluster yang ditentukan:

gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Ganti MEMBERSHIP_NAME dengan nama keanggotaan fleet cluster Anda.

Perintah ini menampilkan kubeconfig khusus gateway Connect khusus yang memungkinkan Anda terhubung ke cluster melalui gateway Connect.

Jika Anda ingin menggunakan akun layanan, bukan akun Google Cloud Anda sendiri, gunakan gcloud config untuk menetapkan auth/impersonate_service_account ke alamat email akun layanan.

Untuk mengambil kredensial cluster yang digunakan untuk berinteraksi dengan gateway Connect menggunakan akun layanan, jalankan perintah berikut: Perhatikan hal berikut:

• Cluster Google Distributed Cloud (khusus software) di bare metal dan VMware: Nama keanggotaan sama dengan nama cluster.

• GKE di AWS: Gunakan gcloud container aws clusters get-credentials.

• GKE di Azure: Gunakan gcloud container azure clusters get-credentials.

Jika Anda ingin menggunakan akun layanan, bukan akun Google Cloud Anda sendiri, gunakan gcloud config untuk menetapkan auth/impersonate_service_account ke alamat email akun layanan. Anda dapat mengetahui lebih lanjut cara mengizinkan pengguna meniru identitas akun layanan di Mengelola akses ke akun layanan.

gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Ganti SA_EMAIL_ADDRESS dengan alamat email akun layanan. Anda dapat mengetahui lebih lanjut cara mengizinkan pengguna meniru identitas akun layanan di Mengelola akses ke akun layanan.

Menjalankan perintah terhadap cluster

Setelah memiliki kredensial yang diperlukan, Anda dapat menjalankan perintah menggunakan kubectl atau go-client seperti biasa untuk cluster Kubernetes apa pun. Output Anda akan terlihat seperti berikut:

# Get namespaces in the Cluster.
kubectl get namespaces
NAME              STATUS   AGE
default           Active   59d
gke-connect       Active   4d

Batasan

Perintah kubectl berikut tidak didukung oleh gateway yang menggunakan perintah gcloud container fleet memberships get-credentials:

• attach
• cp
• exec
• port-forward

Mendukung pratinjau untuk perintah

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dalam Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Perintah attach, cp, dan exec (tetapi bukan port-forward) didukung dengan perintah beta gcloud beta container fleet memberships get-credentials. Perintah ini memungkinkan Anda menggunakan fitur pratinjau gateway Connect.

Perhatikan persyaratan berikut:

• GKE di Google Cloud tidak didukung dalam pratinjau.

• Cluster harus menggunakan versi 1.30 atau yang lebih baru.

• Klien kubectl harus menggunakan versi 1.29 atau yang lebih baru. Jika menggunakan versi 1.29, Anda harus menetapkan variabel lingkungan berikut:

  export KUBECTL_REMOTE_COMMAND_WEBSOCKETS=true
  

  kubectl versi 1.30 dan yang lebih baru tidak memerlukan variabel lingkungan.

  Untuk memeriksa versi klien, lihat output perintah kubectl version. Untuk menginstal versi kubectl yang lebih baru, lihat Menginstal alat.

Pengguna dan akun layanan dengan peran IAM roles/gkehub.gatewayAdmin dan cluster-admin ClusterRole memiliki izin yang diperlukan untuk menjalankan perintah attach, cp, dan exec. Jika pengguna dan akun layanan telah diberi peran IAM kustom atau peran RBAC kustom, Anda mungkin perlu memberikan izin tambahan. Lihat bagian berikut untuk informasi tambahan.

Berikan izin tambahan jika diperlukan

Izin IAM gkehub.gateway.stream diperlukan untuk menjalankan perintah attach, cp, dan exec melalui gateway Connect. Izin ini disertakan dalam roles/gkehub.gatewayAdmin.

Untuk pengguna yang bukan pemilik project, atau untuk pengguna atau akun layanan yang belum diberi roles/gkehub.gatewayAdmin dalam project, Anda harus memberi mereka roles/gkehub.gatewayAdmin atau membuat peran kustom yang menyertakan peran lain yang diperlukan dan izin gkehub.gateway.stream. Untuk mengetahui informasi cara membuat peran khusus, lihat Membuat dan mengelola peran khusus dalam dokumentasi IAM.

Membuat dan menerapkan kebijakan RBAC tambahan jika diperlukan

Pengguna dan akun layanan dengan cluster-admin ClusterRole memiliki izin yang diperlukan untuk menjalankan perintah attach, cp, dan exec.

Setidaknya, aturan berikut diperlukan untuk menjalankan perintah:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: stream-role
  namespace: NAMESPACE  # Specify the namespace
rules:
- apiGroups: ["*"]
  resources: ["pods/exec", "pods/attach"]
  verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: stream-rolebinding
  namespace: NAMESPACE  # Specify the namespace
roleRef:
   apiGroup: "rbac.authorization.k8s.io"
   kind: Role
   name: stream-role
subjects:
- kind: User
  name: EMAIL # Specify the user that should have stream access
  namespace: NAMESPACE  # Specify the namespace

Pemecahan Masalah kubectl exec/cp/attach

Error yang ditampilkan dari menjalankan perintah sering kali tidak cukup jelas untuk men-debug masalah. Dalam hal ini, jalankan kembali perintah dengan tingkat logging verbose yang lebih tinggi, misalnya: kubectl exec -v 5 ....

Jalur beta gateway Connect tidak digunakan

Jika Anda mendapatkan error 400 Bad Request, buat ulang file kubeconfig gateway koneksi menggunakan jalur gcloud CLI beta untuk melihat apakah hal itu memperbaiki error:

gcloud beta container fleet memberships get-credentials my-membership`

Jika Anda masih mendapatkan error 400 Bad Request, ikuti langkah-langkah di bagian berikutnya.

Flag lingkungan kubectl tidak ditetapkan

Jika versi klien kubectl yang Anda gunakan adalah 1.29, variabel lingkungan KUBECTL_REMOTE_COMMAND_WEBSOCKETS harus diaktifkan. Jika tidak diaktifkan, Anda akan mendapatkan error 400 Bad Request. Untuk melihat apakah variabel lingkungan diaktifkan, jalankan perintah berikut:

 echo $KUBECTL_REMOTE_COMMAND_WEBSOCKETS`

Jika variabel tidak ditetapkan, aktifkan dengan menetapkan variabel lingkungan berikut:

export KUBECTL_REMOTE_COMMAND_WEBSOCKETS=true

kubectl versi 1.30 dan yang lebih baru tidak memerlukan flag ini karena diaktifkan secara default.

kubectl versi yang lebih rendah dari 1.29 tidak akan berfungsi dengan fitur ini.

Izin IAM tidak ada

Jika Anda mendapatkan pesan error: error reading from error stream..., hal ini dapat menunjukkan bahwa Anda belum diberi izin IAM yang diperlukan untuk menjalankan perintah. Fitur ini mengharuskan pengguna memiliki izin IAM gkehub.gateway.stream, yang disertakan secara default dalam peran roles/gkehub.gatewayAdmin. Lihat bagian izin IAM untuk mengetahui petunjuknya.

Pesan error generic::failed_precondition: error terjadi dalam cluster

Jika Anda mendapatkan error generic::failed_precondition: error encountered within the cluster, periksa log Agen Connect di cluster untuk mengidentifikasi penyebab utamanya:

kubectl logs -n gke-connect -l app=gke-connect-agent --tail -1

Log yang akan dicari di Connect Agent adalah failed to create the websocket connection....

Izin RBAC yang diperlukan tidak ada

Jika pesan error dalam log Agen Connect berisi 403 Forbidden, hal ini menunjukkan bahwa Anda tidak memiliki izin RBAC. Anda memiliki serangkaian izin RBAC di cluster untuk menjalankan perintah kubectl ini. Lihat bagian Kebijakan RBAC untuk menyiapkan izin RBAC yang diperlukan.

Pesan error generic::resource_exhausted: Kuota active_streams gateway habis

Ada batas kuota 10 streaming aktif per project host fleet. Hal ini ditentukan berdasarkan kuota connectgateway.googleapis.com/active_streams. Lihat artikel Melihat dan mengelola kuota untuk mengetahui petunjuk cara mengelola kuota.

Pesan error generic::failed_precondition: koneksi ke Agen gagal/dihentikan

Jika Anda langsung mengalami error ini saat menjalankan perintah, ada masalah dengan koneksi cluster ke Google. Lihat panduan pemecahan masalah umum untuk mengetahui informasi selengkapnya.

Jika Anda mengalami error ini setelah sekitar 5 hingga 10 menit sesi aktif, ini adalah batasan yang wajar dari fitur tersebut. Koneksi harus dihubungkan kembali.

Pemecahan masalah

Jika Anda mengalami masalah saat menghubungkan ke cluster melalui gateway, Anda atau administrator dapat memeriksa masalah umum berikut.

• Server tidak memiliki jenis resource: Anda mungkin melihat pesan error ini saat perintah kubectl get ns gagal. Ada beberapa kemungkinan alasan terjadinya error ini. Jalankan perintah kubectl dalam mode panjang untuk melihat detail selengkapnya, misalnya kubectl get ns -v 10.
• Tidak dapat menemukan koneksi aktif untuk cluster(project: 12345, membership: my-cluster): Anda mungkin melihat error ini saat Agen Connect kehilangan konektivitas atau tidak diinstal dengan benar (khusus cluster di luar Google Cloud). Untuk mengatasi masalah ini, Anda perlu memverifikasi apakah namespace gke-connect ada di cluster. Jika namespace gke-connect ada di cluster, lihat halaman Pemecahan Masalah Koneksi untuk memperbaiki masalah konektivitas.
• URL yang diminta tidak ditemukan di server ini: Anda mungkin melihat error ini jika kubeconfig berisi alamat server yang salah. Pastikan versi Google Cloud CLI yang Anda gunakan adalah versi terbaru dan coba lagi untuk membuat gateway kubeconfig. Jangan mengedit file kubeconfig secara manual, karena akan menyebabkan error yang tidak terduga.
• Identitas pengguna tidak memiliki izin yang memadai untuk menggunakan API gateway: Anda memerlukan peran roles/gkehub.gatewayAdmin roles/gkehub.gatewayReader atau roles/gkehub.gatewayEditor untuk menggunakan API. Lihat Memberikan peran IAM kepada pengguna di panduan penyiapan gateway untuk mengetahui detail selengkapnya.
• Agen Connect tidak diberi otorisasi untuk mengirim permintaan pengguna: Agen Connect harus diizinkan untuk meneruskan permintaan atas nama Anda, yang ditentukan menggunakan kebijakan peniruan identitas di cluster. Lihat Mengonfigurasi otorisasi RBAC di panduan penyiapan gateway untuk mengetahui contoh penambahan pengguna ke peran gateway-impersonate.
• Identitas pengguna tidak memiliki izin RBAC yang memadai untuk melakukan operasi: Anda harus memiliki izin yang sesuai di cluster untuk menjalankan operasi yang dipilih. Lihat Mengonfigurasi otorisasi RBAC di panduan penyiapan gateway untuk mengetahui contoh cara menambahkan pengguna ke ClusterRole yang sesuai.
• Identitas pengguna tidak memiliki izin yang memadai untuk melakukan operasi saat menggunakan Google Grup atau dukungan pihak ketiga: Lihat Mengumpulkan log Identity Service GKE untuk mengetahui petunjuk tentang cara memeriksa log yang terkait dengan informasi identitas.
• Agen Connect tidak berfungsi: Lihat halaman Pemecahan Masalah Connect untuk memastikan cluster Anda terhubung.
• executable gke-gcloud-auth-plugin not found atau no Auth Provider found for name gcp: kubectl versi 1.26 dan yang lebih baru dapat menampilkan error ini karena perubahan pada autentikasi kubectl mulai dari GKE v1.26. Instal gke-gcloud-auth-plugin dan jalankan kembali gcloud container fleet memberships get-credentials MEMBERSHIP_NAME dengan Google Cloud CLI versi terbaru.
• Koneksi ke gateway gagal dengan Google Cloud CLI versi lama: Untuk cluster GKE, agen Connect tidak lagi diperlukan agar gateway berfungsi sehingga tidak diinstal secara default selama pendaftaran langganan. Google Cloud CLI versi sebelumnya (399.0.0 dan yang lebih lama) mengasumsikan keberadaan agen Connect di cluster. Mencoba menggunakan gateway dengan versi sebelumnya ini dapat gagal di cluster yang terdaftar dengan Google Cloud CLI versi yang lebih baru. Untuk mengatasinya, upgrade klien Google Cloud CLI Anda ke versi yang lebih baru atau jalankan kembali perintah pendaftaran langganan dengan flag --install-connect-agent.

Apa langkah selanjutnya?

• Lihat contoh cara menggunakan gateway Connect sebagai bagian dari otomatisasi DevOps Anda dalam tutorial Mengintegrasikan dengan Cloud Build.