Menggunakan gateway Connect

Halaman ini menjelaskan cara menggunakan Connect gateway untuk terhubung ke cluster terdaftar. Sebelum membaca halaman ini, pastikan Anda 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

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk menggunakan Connect gateway guna terhubung ke cluster dan menjalankan perintah, minta administrator untuk memberi Anda peran IAM berikut di project cluster:

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran Connect Gateway Admin (roles/gkehub.gatewayAdmin) adalah satu-satunya peran yang telah ditetapkan yang berisi izin gkehub.gateway.stream, yang diperlukan untuk menjalankan perintah kubectl CLI seperti attach, exec, port-forward, dan cp.

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Login keakun Anda Google Cloud

Anda dapat menggunakanakun Anda sendiri atauakun layanan untuk berinteraksi dengan cluster yang terhubung melalui Gateway API. Google Cloud Google Cloud

Ikuti petunjuk di Mengotorisasi alat Google Cloud CLI untuk login ke akun pengguna Anda. Connect gateway 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 fleet saat ini dengan menjalankan perintah berikut:

gcloud container fleet memberships list

Perintah ini akan 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 projectnya saat pendaftaran.

Mendapatkan kubeconfig gateway cluster

Gunakan perintah berikut untuk mendapatkan kubeconfig yang Anda perlukan 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 Connect gatewaykubeconfig yang memungkinkan Anda terhubung ke cluster melalui Connect gateway.

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

Untuk mengambil kredensial cluster yang digunakan untuk berinteraksi dengan Connect gateway 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.

Anda dapat mengetahui lebih lanjut cara mengizinkan pengguna meniru 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 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 biasanya untuk cluster Kubernetes mana 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

Perintah kubectl exec/cp/attach/port-forward

Perintah kubectl berikut adalah perintah streaming dan memiliki persyaratan tambahan:

  • attach
  • cp
  • exec
  • port-forward

Untuk menjalankan perintah ini, Anda harus memenuhi persyaratan berikut:

  • Cluster harus menggunakan versi 1.30 atau yang lebih baru untuk perintah attach, cp, dan exec, serta versi 1.31 atau yang lebih baru untuk perintah port-forward.

  • Klien kubectl harus menggunakan versi 1.31 atau yang lebih baru. Untuk memeriksa versi klien Anda, lihat output perintah kubectl version. Untuk menginstal versi kubectlyang lebih baru, lihat Menginstal alat.

  • Pengguna dan akun layanan harus memiliki akses tambahan berikut ke Kubernetes API melalui IAM atau RBAC:

    • IAM: berikan peran yang menyertakan izin gkehub.gateway.stream. Peran yang telah ditetapkan roles/gkehub.gatewayAdmin menyertakan izin ini. Anda juga dapat menetapkan izin ini ke peran khusus.

    • RBAC: berikan Peran atau ClusterRole yang menyertakan akses get ke subresource API pods/exec, pods/portforward, dan pods/attach, seperti dalam contoh Peran dan RoleBinding berikut:

      apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: stream-role
  namespace: NAMESPACE # Specify the namespace
rules:
- apiGroups: ["*"]
  resources: ["pods/exec", "pods/attach", "pods/portforward"]
  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: Group
  name: EMAIL # Specify the group that should have stream access

      Ganti kode berikut:

      • NAMESPACE: namespace untuk Peran dan RoleBinding.
      • EMAIL: alamat email grup yang harus memiliki akses streaming, jika cluster mendukung RBAC dengan grup.

      ClusterRole default cluster-admin juga menyertakan izin ini.

Pemecahan masalah

Jika Anda mengalami masalah saat terhubung ke cluster melalui gateway, Anda atau administrator Anda 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 penyebab error ini. Jalankan perintah kubectl dalam mode verbose 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 Connect Agent kehilangan konektivitas atau tidak diinstal dengan benar (khusus cluster di luar Google Cloud ). Untuk mengatasi masalah ini, Anda harus memverifikasi apakah namespace gke-connect ada di cluster. Jika namespace gke-connect ada di cluster, lihat halaman Pemecahan Masalah Connect untuk memperbaiki masalah konektivitas.
  • The requested URL was not found on this server: Anda mungkin melihat error ini saat 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, yang 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.
  • The Connect agent is not authorized to send the user’s requests: Connect agent harus diizinkan untuk meneruskan permintaan atas nama Anda, yang ditentukan menggunakan kebijakan peniruan di cluster. Lihat Mengonfigurasi otorisasi RBAC di panduan penyiapan gateway untuk mengetahui contoh cara menambahkan 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 Layanan Identitas GKE untuk mengetahui petunjuk cara memeriksa log terkait informasi identitas.
  • Agen Connect tidak sehat: 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 mungkin menampilkan error ini karena perubahan pada autentikasi kubectl yang dimulai dengan 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 versi Google Cloud CLI yang lebih lama: Untuk cluster GKE, Connect agent tidak lagi diperlukan agar gateway berfungsi sehingga tidak diinstal secara default selama pendaftaran keanggotaan. Versi Google Cloud CLI sebelumnya (399.0.0 dan di bawahnya) mengasumsikan keberadaan Connect agent di cluster. Mencoba menggunakan gateway dengan versi sebelumnya ini mungkin akan gagal di cluster yang terdaftar dengan Google Cloud CLI versi yang lebih baru. Untuk mengatasinya, upgrade klien Google Cloud CLI ke versi yang lebih baru atau jalankan kembali perintah pendaftaran keanggotaan dengan tanda --install-connect-agent.
  • The size of groups returned under the gke-security-groups group exceeds the 8 KB HTTP header size limit. Reorganisasi hierarki grup dan coba lagi: Meskipun tidak ada batas tetap untuk jumlah grup, nama grup yang panjang dapat menyebabkan permintaan melebihi batas ukuran header HTTP 8 KB dan mengakibatkan error yang mungkin mengharuskan Anda menyusun ulang hierarki grup.

Pemecahan masalah kubectl exec/cp/attach/port-forward

Error yang ditampilkan dari menjalankan perintah sering kali merupakan error 400 Bad Request umum yang tidak cukup jelas untuk men-debug masalah. Untuk menampilkan pesan error yang lebih mendetail, gunakan klien kubectl versi 1.32 atau yang lebih baru untuk menjalankan perintah dengan verbositas level 4 atau yang lebih tinggi, misalnya: kubectl exec -v 4 ....

Dalam log yang ditampilkan, telusuri log yang berisi respons berikut:

  • Untuk perintah kubectl exec/cp/attach: RemoteCommand fallback:
  • Untuk perintah kubectl port-forward: fallback to secondary dialer from primary dialer err:

Untuk memecahkan masalah beberapa pesan error umum yang mungkin Anda terima dari perintah kubectl exec -v 4 ..., lihat bagian berikut.

Izin IAM tidak ada

Jika pesan error berisi generic::permission_denied: Permission'gkehub.gateway.stream' denied on resource, 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.

Izin RBAC yang diperlukan tidak ada

Jika pesan error berisi ...generic::failed_precondition: failed to connect to the cluster's API Server with response (status=403 Forbidden..., hal ini menunjukkan bahwa Anda tidak memiliki izin RBAC. Anda memerlukan serangkaian izin RBAC di cluster untuk menjalankan perintah kubectl ini. Untuk mengetahui informasi selengkapnya tentang cara menyiapkan izin RBAC yang diperlukan, lihat Membuat dan menerapkan kebijakan RBAC tambahan jika diperlukan.

Pesan error generic::resource_exhausted: Gateway's active_streams quota exhausted

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

Pesan error generic::failed_precondition: error encountered within the cluster

Jika Anda mendapatkan error generic::failed_precondition: error encountered within the cluster, periksa log Connect Agent di cluster untuk mengidentifikasi penyebab yang mendasarinya:

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

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

Pesan error generic::failed_precondition: connection to Agent failed/terminated

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 sesi aktif selama sekitar 20 hingga 30 menit, hal ini merupakan batasan yang diharapkan karena alasan keamanan. Koneksi harus dibuat ulang.

Pemecahan masalah kubectl --raw

Menggunakan endpoint yang disingkat (seperti kubectl get --raw /version) dapat menyebabkan error berikut: Error from server (NotFound): the server could not find the requested resource. Anda harus memberikan alamat server lengkap.

Ambil endpoint dari kubeconfig Anda:

# e.g. https://connectgateway.googleapis.com/v1/projects/1234567/locations/global/gkeMemberships/my-membership
FULL_GATEWAY_ENDPOINT=$(kubectl config view --minify -o jsonpath='{.clusters[*].cluster.server}')
echo $FULL_GATEWAY_ENDPOINT

Kemudian, gunakan endpoint untuk perintah Anda, misalnya, dengan /version:

kubectl get --raw $FULL_GATEWAY_ENDPOINT/version

Apa langkah selanjutnya?