Menggunakan gateway Connect
Halaman ini menjelaskan cara menggunakan gateway Connect untuk terhubung ke cluster terdaftar. Sebelum membaca panduan ini, Anda harus sudah 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:
- Versi terbaru Google Cloud CLI, yaitu 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 sendiri, Anda dapat menggunakan akun layanan untuk berinteraksi dengan cluster, seperti yang akan Anda lihat di bagian berikut.
Pilih cluster terdaftar
Jika tidak mengetahui nama cluster yang ingin diakses, Anda dapat melihat semua cluster fleet yang terdaftar saat ini dengan menjalankan perintah berikut:
gcloud container fleet memberships list
Tindakan ini akan mencantumkan semua cluster fleet Anda, termasuk nama keanggotaan dan ID eksternal. 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 tersebut tidak unik dalam project-nya pada 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 keanggotaan fleet cluster Anda
nama.
Perintah ini menampilkan kubeconfig
khusus gateway Connect khusus yang
memungkinkan Anda terhubung ke cluster melalui gateway Connect.
Jika Anda ingin menggunakan akun layanan
dan bukan akun Google Cloud Anda sendiri,
gunakan gcloud config
untuk menetapkan auth/impersonate_service_account
ke layanan
alamat email Anda.
Untuk mengambil kredensial cluster yang digunakan untuk berinteraksi dengan gateway Connect menggunakan akun layanan, jalankan perintah berikut: Perhatikan hal berikut:
- Google Distributed Cloud (khusus software) cluster pada bare metal dan VMware: Nama keanggotaan sama dengan nama cluster.
GKE di AWS: Gunakan
gcloud container aws clusters get-credentials
.GKE di Azure: Menggunakan
gcloud container azure clusters get-credentials
.
Jika Anda ingin menggunakan akun layanan dan bukan akun Google Cloud Anda sendiri, gunakan gcloud config
untuk menyetel 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 yang biasa Anda lakukan 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
Batasan
Perintah kubectl
berikut tidak didukung oleh gateway
menggunakan perintah gcloud container fleet memberships get-credentials
:
attach
cp
exec
port-forward
Dukungan pratinjau untuk perintah
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
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 Anda, lihat {i>output<i} dari Perintah
kubectl version
. Untuk menginstal versi yang lebih baru darikubectl
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 khusus atau
peran RBAC khusus, Anda mungkin perlu
memberikan izin tambahan. Lihat
bagian berikut untuk informasi tambahan.
Berikan izin tambahan jika diperlukan
Izin IAM gkehub.gateway.stream
diperlukan agar dapat dijalankan
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
roles/gkehub.gatewayAdmin
belum diberikan dalam project ini, Anda harus
memberi mereka roles/gkehub.gatewayAdmin
atau membuat peran khusus yang
mencakup peran lain yang diperlukan dan gkehub.gateway.stream
izin akses. Untuk mengetahui informasi cara membuat peran khusus, lihat
Membuat dan mengelola peran khusus dalam
dokumentasi IAM.
Buat dan terapkan 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
kubectl exec/cp/attach Pemecahan Masalah
Error yang ditampilkan dari menjalankan perintah sering kali tidak cukup jelas untuk di-debug
menyelesaikan masalah. Dalam hal ini, jalankan kembali perintah dengan logging verbositas yang lebih tinggi
level, misalnya: kubectl exec -v 5 ...
.
Jalur beta gateway Connect tidak digunakan
Jika Anda mendapatkan error 400 Bad Request
, buat ulang gateway koneksi
file kubeconfig menggunakan jalur beta gcloud CLI untuk melihat apakah
memperbaiki {i>error<i}:
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, lingkungan
variabel 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 lingkungan berikut variabel:
export KUBECTL_REMOTE_COMMAND_WEBSOCKETS=true
kubectl versi 1.30 dan yang lebih baru tidak memerlukan flag ini karena diaktifkan secara default.
kubectl versi 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...
, artinya
dapat menunjukkan bahwa Anda belum diberi IAM yang diperlukan
izin akses untuk
menjalankan perintah tersebut. 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 generik::failed_precondition: error ditemukan dalam cluster
Jika Anda mendapatkan error generic::failed_precondition: error encountered within
the cluster
, periksa log Agen Connect di cluster untuk mengidentifikasi
penyebab yang mendasari:
kubectl logs -n gke-connect -l app=gke-connect-agent --tail -1
Log yang harus dicari di
Agen Connect adalah
failed to create the websocket connection...
.
Izin RBAC yang diperlukan tidak ada
Jika pesan error di log Connect Agent berisi 403 Forbidden
,
hal ini menunjukkan bahwa
Anda tidak memiliki izin RBAC. Anda memiliki sekumpulan RBAC
dalam cluster untuk menjalankan perintah kubectl ini.
Lihat
Bagian Kebijakan RBAC
untuk mengatur izin akses RBAC yang diperlukan.
Pesan error generik::resource_exhausted: Kuota active_streams gateway habis
Ada batas kuota 10 streaming aktif per project host fleet. Ini adalah
yang ditentukan dalam kuota connectgateway.googleapis.com/active_streams
. Lihat
Lihat dan kelola kuota untuk mengetahui petunjuk cara mengelola
kuota Anda.
Pesan error generik::failed_precondition: koneksi ke Agen gagal/dihentikan
Jika Anda langsung mengalami {i>error<i} ini saat menjalankan perintah, ada masalah terkait koneksi cluster ke Google. Lihat pertanyaan umum panduan pemecahan masalah untuk informasi selengkapnya.
Jika Anda mengalami error ini setelah sekitar 5 hingga 10 menit sesi aktif, ini adalah batasan yang wajar dari fitur tersebut. Tujuan koneksi perlu dibuat kembali.
Pemecahan masalah
Jika 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 perintahkubectl
dalam mode panjang untuk melihat detail selengkapnya, misalnyakubectl get ns -v 10
. - Tidak dapat menemukan koneksi aktif untuk cluster(project: 12345, langganan: my-cluster): Anda mungkin melihat error ini saat Connect Agent kehilangan konektivitas atau tidak diinstal dengan benar (cluster di luar Google Cloud saja). Untuk mengatasi masalah ini, Anda perlu memverifikasi apakah namespace
gke-connect
ada di cluster. Jika namespacegke-connect
ada di cluster, lihat halaman Pemecahan Masalah Menghubungkan 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 gatewaykubeconfig
. Jangan edit filekubeconfig
secara manual, karena akan menyebabkan error tidak terduga. - Identitas pengguna tidak memiliki izin yang memadai untuk menggunakan gateway API: Anda memerlukan peran
roles/gkehub.gatewayAdmin
roles/gkehub.gatewayReader
atauroles/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 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 contoh penambahan pengguna ke
ClusterRole
yang sesuai. - Identitas pengguna tidak memiliki izin yang memadai untuk menjalankan operasi saat menggunakan Google Grup atau dukungan pihak ketiga: Lihat Mengumpulkan log GKE Identity Service untuk mengetahui petunjuk cara memeriksa log terkait informasi identitas.
- Agen Connect tidak responsif: Lihat halaman Pemecahan Masalah Connect untuk memastikan cluster Anda terhubung.
- executable gke-gcloud-auth-plugin not found atau tidak ada Auth Provider yang ditemukan untuk nama 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 kembaligcloud container fleet memberships get-credentials MEMBERSHIP_NAME
dengan versi terbaru Google Cloud CLI. - Koneksi ke gateway gagal dengan versi lama Google Cloud CLI: Untuk cluster GKE, agen Connect tidak lagi diperlukan agar gateway dapat berfungsi sehingga tidak diinstal secara default selama pendaftaran keanggotaan. Google Cloud CLI versi sebelumnya (399.0.0 dan yang lebih lama) mengasumsikan keberadaan agen Connect di cluster. Upaya menggunakan gateway dengan versi sebelumnya ini mungkin akan gagal pada cluster yang terdaftar dengan versi Google Cloud CLI yang lebih baru. Untuk mengatasi hal ini, upgrade klien Google Cloud CLI Anda ke versi yang lebih baru atau jalankan ulang perintah pendaftaran keanggotaan dengan flag
--install-connect-agent
.
Apa langkah selanjutnya?
- Lihat contoh cara menggunakan gateway Connect sebagai bagian dari otomatisasi DevOps dalam tutorial Mengintegrasikan dengan Cloud Build kami.