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 serta izin yang diperlukan.
Sebelum memulai
Pastikan Anda telah menginstal alat command line berikut:
- Versi terbaru Google Cloud CLI, alat command line untuk berinteraksi dengan Google Cloud.
kubectl
Jika Anda menggunakan Cloud Shell sebagai lingkungan shell untuk berinteraksi dengan Google Cloud, alat ini diinstal untuk Anda.
Pastikan Anda telah melakukan inisialisasi gcloud CLI untuk digunakan dengan project.
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 bagian Memberi otorisasi pada alat Google Cloud CLI untuk login ke akun pengguna Anda. Gateway Connect mendukung peniruan identitas 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 yang terdaftar
Jika tidak mengetahui nama cluster yang ingin diakses, Anda dapat melihat semua cluster terdaftar fleet Anda saat ini dengan menjalankan perintah berikut:
gcloud container fleet memberships list
Tindakan ini akan mencantumkan semua cluster fleet Anda, termasuk nama keanggotaan dan ID eksternalnya. Setiap cluster dalam fleet memiliki nama keanggotaan unik. Untuk cluster GKE, nama keanggotaan umumnya sama dengan nama yang Anda berikan saat membuat cluster, kecuali jika nama cluster tidak unik dalam project pada saat pendaftaran.
Mendapatkan kubeconfig
gateway cluster
Gunakan perintah berikut untuk mendapatkan kubeconfig
yang diperlukan untuk berinteraksi dengan cluster yang Anda tentukan, dengan mengganti MEMBERSHIP_NAME
dengan nama keanggotaan fleet cluster Anda. Perintah ini menampilkan kubeconfig
khusus gateway Connect khusus yang memungkinkan Anda terhubung ke cluster melalui gateway.
# Fetch cluster credential used to interact with Connect gateway
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME
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 mencari tahu lebih lanjut tentang cara mengizinkan pengguna meniru identitas akun layanan di Mengelola akses ke akun layanan.
# Fetch cluster credential used to interact with Connect gateway, using a service account
gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME
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 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
Perintah kubectl
berikut tidak didukung oleh gateway:
exec
proxy
port-forward
attach
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 sederhana seperti
kubectl get ns
gagal. Ada beberapa kemungkinan alasan untuk kesalahan ini. Jalankan perintah kubectl dalam mode panjang untuk melihat detail selengkapnya, misalnyakubectl get ns -v 10
. - Tidak dapat menemukan koneksi aktif untuk cluster(project: 12345, keanggotaan: my-cluster): Anda mungkin melihat error ini saat Connect Agent kehilangan konektivitas atau tidak diinstal dengan benar. Untuk mengatasi masalah ini, Anda perlu memverifikasi apakah namespace
gke-connect
ada di cluster. Jika tidak, lihat Mendaftarkan cluster dengan Google Cloud CLI. Jika namespacegke-connect
ada di cluster, lihat halaman Pemecahan Masalah Hubungkan untuk memperbaiki masalah konektivitas. - URL yang diminta tidak ditemukan di server ini: Anda akan melihat error ini jika
kubeconfig
berisi alamat server yang salah. Pastikan versi Google Cloud CLI yang Anda gunakan adalah versi terbaru, lalu coba lagi untuk membuat gatewaykubeconfig
. Jangan mengedit filekubeconfig
secara manual, yang 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 diizinkan 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 menjalankan operasi: Anda harus memiliki izin yang sesuai di cluster untuk menjalankan operasi yang Anda pilih. 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 menjalankan operasi saat menggunakan Google Grup atau dukungan pihak ketiga: Lihat Mengumpulkan log GKE Identity Service untuk mendapatkan petunjuk tentang cara memeriksa log yang terkait dengan informasi identitas.
- Agen Connect tidak responsif: 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 mulai dari 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 Google Cloud CLI versi lama: Untuk cluster GKE, agen Connect tidak lagi diperlukan agar gateway dapat berfungsi sehingga tidak diinstal secara default selama pendaftaran keanggotaan. Versi lama Google Cloud CLI (399.0.0 dan yang lebih lama) mengasumsikan keberadaan agen Connect di cluster. Mencoba menggunakan gateway dengan versi lama 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 ke versi yang lebih baru atau jalankan kembali 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.