Gemini CLI di GCE dengan endpoint Private Service Connect

1. Ringkasan

Anda dapat menggunakan Gemini CLI di lingkungan lokal dan virtual. Gemini CLI adalah agen AI open source yang menghadirkan kecanggihan Gemini langsung ke terminal Anda. Dari sudut pandang jaringan, saat Anda menggunakan Gemini CLI, CLI tersebut akan melakukan panggilan ke Gemini API melalui alamat IP API yang dapat diakses secara publik.

Lalu, apa yang terjadi jika Anda ingin menggunakan Gemini CLI di mesin Google Compute Engine, tetapi Anda ingin terhubung ke API secara pribadi? Dalam codelab ini, Anda akan melihat cara mengonfigurasi endpoint Private Service Connect ke Google API, untuk merutekan traffic ke alamat IP internal yang Anda tentukan.

Konfigurasi akan berupa kombinasi Terraform, gcloud, dan konsol.

Di lab ini, Anda akan mempelajari cara melakukan tugas berikut:

• Siapkan instance VM dan Cloud NAT
• Menginstal dan mengautentikasi Gemini CLI
• Mengonfigurasi endpoint Private Service Connect untuk terhubung ke Googleapis
• Memverifikasi jalur konektivitas ke *.googleais
• Mengonfigurasi entri DNS manual

Di lab ini, Anda akan membuat pola berikut.

Gambar 1.

2. Penyiapan layanan Google Cloud

Penyiapan lingkungan mandiri

1. Login ke Google Cloud Console dan buat project baru atau gunakan kembali project yang sudah ada. Jika belum memiliki akun Gmail atau Google Workspace, Anda harus membuatnya.

• Project name adalah nama tampilan untuk peserta project ini. String ini adalah string karakter yang tidak digunakan oleh Google API. Anda dapat memperbaruinya kapan saja.
• Project ID bersifat unik di semua project Google Cloud dan tidak dapat diubah (tidak dapat diubah setelah ditetapkan). Cloud Console otomatis membuat string unik; biasanya Anda tidak mementingkan kata-katanya. Di sebagian besar codelab, Anda harus merujuk Project ID-nya (umumnya diidentifikasi sebagai PROJECT_ID). Jika tidak suka dengan ID yang dibuat, Anda dapat membuat ID acak lainnya. Atau, Anda dapat mencobanya sendiri, dan lihat apakah ID tersebut tersedia. ID tidak dapat diubah setelah langkah ini dan tersedia selama durasi project.
• Sebagai informasi, ada nilai ketiga, Project Number, yang digunakan oleh beberapa API. Pelajari lebih lanjut ketiga nilai ini di dokumentasi.

Perhatian: Project ID bersifat unik secara global dan tidak dapat digunakan orang lain setelah Anda memilihnya. Anda adalah satu-satunya pengguna ID tersebut. Meskipun project sudah dihapus, ID tersebut tidak dapat digunakan lagi

Catatan: Jika menggunakan akun Gmail, Anda dapat menyetel lokasi default ke No organization. Jika Anda menggunakan akun Google Workspace, pilih lokasi yang sesuai untuk organisasi Anda.

2. Selanjutnya, Anda harus mengaktifkan penagihan di Konsol Cloud untuk menggunakan resource/API Cloud. Menjalankan operasi dalam codelab ini tidak akan memakan banyak biaya, bahkan mungkin tidak sama sekali. Guna mematikan resource agar tidak menimbulkan penagihan di luar tutorial ini, Anda dapat menghapus resource yang dibuat atau menghapus project-nya. Pengguna baru Google Cloud memenuhi syarat untuk mengikuti program Uji Coba Gratis senilai $300 USD.

Mulai Cloud Shell

Meskipun Google Cloud dapat dioperasikan dari jarak jauh menggunakan laptop Anda, dalam codelab ini, Anda akan menggunakan Google Cloud Shell, lingkungan command line yang berjalan di Cloud.

Dari Google Cloud Console, klik ikon Cloud Shell di toolbar kanan atas:

Hanya perlu waktu beberapa saat untuk penyediaan dan terhubung ke lingkungan. Jika sudah selesai, Anda akan melihat tampilan seperti ini:

Mesin virtual ini berisi semua alat pengembangan yang Anda perlukan. Layanan ini menawarkan direktori beranda tetap sebesar 5 GB dan beroperasi di Google Cloud, sehingga sangat meningkatkan performa dan autentikasi jaringan. Semua pekerjaan Anda dalam codelab ini dapat dilakukan di browser. Anda tidak perlu menginstal apa pun.

3. Tugas 1. Menyiapkan lingkungan dengan terraform

Kita akan membuat VPC kustom dengan aturan Firewall dan subnet. Buka konsol cloud dan pilih project yang akan Anda gunakan.

1. Buka Cloud Shell yang berada di bagian atas konsol Anda di sebelah kanan, pastikan Anda melihat project id yang benar di Cloud Shell, dan konfirmasi setiap perintah untuk mengizinkan akses.
2. Buat folder bernama terraform-build dan pindahkan ke folder

mkdir terraform-build  && cd terraform-build

3. Buat file main.tf dan variable.tf.

touch main.tf variable.tf 

4. Beralihlah ke tampilan Cloud Shell Editor. Pilih editor, pastikan Anda mengizinkan perintah yang diperlukan agar antarmuka dapat dimuat.
5. Setelah dimuat, buka File > Open Folder, lalu buka /home/your-user-name/terraform-build, dan pilih Ok untuk membuka folder di editor.
6. Pilih file variable.tf dan tambahkan kode berikut. Ganti teks your-project-id-here dengan project ID Anda yang sebenarnya dalam tanda petik

variable "project_id" {
  type = string
  default = "your-project-id-here"
}

variable "network_id" {
  type = string
  default = "gemini-vpc-net"
}

7. Selanjutnya, buka file main.tf. Kita akan menambahkan beberapa kode terraform untuk melakukan berbagai tindakan seperti yang dijelaskan di bawah.

Mengaktifkan API	resource "google_project_service" "default"
Buat VPC bernama python-net	resource "google_compute_network" "default"
Menambahkan subnet	resource "google_compute_subnetwork" "default"
Tambahkan dua aturan Firewall	resource "google_compute_firewall" "allow_icmp"resource "google_compute_firewall" "allow_ssh"

8. Salin dan tempel kode berikut ke dalam file main .tf.

resource "google_project_service" "default" {
  for_each = toset([
    "dns.googleapis.com",
    "aiplatform.googleapis.com",
    "servicedirectory.googleapis.com"
  ])

  service            = each.value
  disable_on_destroy = false
}

resource "google_compute_network" "default" {
  project                 = var.project_id
  name                    = var.network_id
  auto_create_subnetworks = false
  mtu                     = 1460
  routing_mode            = "GLOBAL"
}

resource "google_compute_subnetwork" "default" {
  name          = "vm1-subnet"
  ip_cidr_range = "192.168.100.0/24"
  region        = "us-east1"
  stack_type    = "IPV4_ONLY"
  network       = google_compute_network.default.id
}

resource "google_compute_firewall" "allow_icmp" {
  name    = "allow-icmp-${google_compute_network.default.name}"
  network = google_compute_network.default.id
  project = var.project_id

  allow {
    protocol = "icmp"
  }

  source_ranges = ["0.0.0.0/0"]
  target_tags   = ["allow-icmp"]
}

resource "google_compute_firewall" "allow_ssh" {
  name    = "allow-ssh-${google_compute_network.default.name}"
  network = google_compute_network.default.id
  project = var.project_id

  allow {
    protocol = "tcp"
    ports    = ["22"]
  }

  source_ranges = ["0.0.0.0/0"]
  target_tags   = ["allow-ssh"]
}

9. Beralih kembali ke terminal Cloud Shell, pastikan Anda berada di direktori terraform-build cd terraform-build, lalu jalankan perintah berikut

terraform init

Menginisialisasi direktori kerja. Langkah ini mendownload penyedia yang diperlukan untuk konfigurasi tertentu.

terraform plan

Membuat rencana eksekusi, yang menunjukkan tindakan yang akan dilakukan Terraform untuk men-deploy infrastruktur Anda.

10. Sekarang untuk membuat resource, jalankan perintah terraform apply dan ketik yes untuk menjalankan.

Verifikasi penyiapan Anda: Periksa lingkungan Anda untuk

• VPC bernama gemini-vpc-net
• subnet
• firewall-rules

4. Tugas 2. Membuat gateway NAT dan VM dengan Terraform

Kita perlu memberikan akses eksternal keluar ke internet, jadi mari buat dan lampirkan gateway Cloud NAT.

1. Buka Cloud Shell, buka folder terraform-build, lalu buat file berikut (total tiga file). Kita akan mengeditnya nanti.

touch nat-vm.tf psc.tf dns.tf

2. Beralihlah ke tampilan Cloud Shell editor, pilih file nat-vm.tf, lalu tambahkan kode Terraform berikut. Tindakan ini akan membuat gateway NAT dan dua VM.

Terraform nat-vm.tf

resource "google_compute_router" "default" {
  name    = "outbound-nat"
  region  = "us-east1"
  network = google_compute_network.default.id

 bgp {
  asn = 64514
  }
}

resource "google_compute_router_nat" "default" {
  name                               = "outbound-gw"
  router                             = google_compute_router.default.name
  region                             = google_compute_router.default.region
  nat_ip_allocate_option             = "AUTO_ONLY"
  source_subnetwork_ip_ranges_to_nat = "ALL_SUBNETWORKS_ALL_IP_RANGES"

  log_config {
    enable = true
    filter = "ERRORS_ONLY"
  }
}

resource "google_compute_instance" "vm1" {
  name         = "cli-vm"
  zone         = "us-east1-b"
  machine_type = "n2-standard-2"

  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-12"
    }
  }

  network_interface {
    subnetwork = google_compute_subnetwork.default.id  
    stack_type = "IPV4_ONLY"
  }

  tags = ["allow-ssh", "allow-icmp"]

  metadata_startup_script = <<-EOF
    sudo apt-get update    
  EOF
}

resource "google_compute_instance" "vm2" {
  name         = "monitor-vm"
  zone         = "us-east1-b"
  machine_type = "n2-standard-2"

  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-12"
    }
  }

  network_interface {
    subnetwork = google_compute_subnetwork.default.id   
    stack_type = "IPV4_ONLY"
  }

  tags = ["allow-ssh", "allow-icmp"]

  metadata_startup_script = <<-EOF
    sudo apt-get update
    sudo apt-get install python3 python3-dev python3-venv -y
    sudo apt-get install tcpdump dnsutils -y
  EOF
}

3. Beralihlah ke terminal Cloud Shell, pastikan Anda berada di folder terraform-build, lalu jalankan terraform plan. Perintah ini akan menunjukkan bahwa 4 item akan ditambahkan, lalu jalankan terraform apply dan ketik yes untuk membuat gateway NAT dan dua VM.

Verifikasi penyiapan Anda: Periksa lingkungan Anda untuk

1 gateway NAT

1 cloud router

VM bernama cli-vm

VM bernama monitor-vm

5. Tugas 3. Mengonfigurasi VM CLI dan menguji

1. Buka instance VM. Pilih VM yang dimulai dengan cli-vm. Pilih SSH.
2. Setelah Anda melakukan SSH, Anda akan memiliki akses ke VM. Mari kita buat folder untuk saat kita menjalankan Gemini CLI

mkdir geminicli && cd geminicli

3. Untuk menginstal Gemini CLI, kita memerlukan Node.js. Instal node JS menggunakan perintah berikut

curl -fsSL https://deb.nodesource.com/setup_24.x -o nodesource_setup.sh

Jalankan skrip

sudo -E bash nodesource_setup.sh

Instal Node.js

sudo apt-get install -y nodejs

4. Mari kita tetapkan beberapa variabel yang akan membantu penggunaan opsi autentikasi Vertex AI untuk mengautentikasi ini guna melakukan beberapa pengujian nanti. p.s. Ganti YOUR_PROJECT_ID dengan project ID Anda yang sebenarnya

cat <<EOF >> ~/.bashrc 

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="us-east1" 
export GOOGLE_GENAI_USE_VERTEXAI=true
EOF

Muat ulang bash

source ~/.bashrc

5. Sekarang, mari kita lakukan autentikasi. Jalankan perintah berikut di VM, tekan y saat diminta.

gcloud auth application-default login

6. Selanjutnya, salin URL yang muncul, yang dimulai dengan https://, buka tab baru di jendela browser lab Anda, lalu tempel URL tersebut. Setujui perintah.
7. Saat Anda melihat perintah berikut, pilih salin, kembali ke sesi cli-vm VM, dan untuk Enter authorization code:, tempel kode yang Anda salin, lalu tekan enter untuk melakukan autentikasi.

8. Sekarang, instal Gemini CLI dengan menjalankan perintah

sudo npm install -g @google/gemini-cli

Setelah selesai, ketik gemini untuk meluncurkan antarmuka, pilih tema yang Anda sukai, dan di bagian Select Auth method, pilih Vertex AI

9. Setelah diautentikasi, Anda dapat mulai menggunakan Gemini CLI

Catatan: Anda dapat mengubah pertanyaan perintah menjadi sesuatu yang lain.

Memantau rute traffic ke Gemini melalui monitor vm

1. Buka instance VM. Pilih VM yang dimulai dengan monitor-vm. Pilih SSH.
2. Setelah melakukan SSH ke monitor-vm, Anda akan memiliki akses
3. Mari kita gunakan perintah dig untuk menguji jalur koneksi ke Gemini API. Kita akan menggunakan us-east1-aiplatform.googleapis.com

dig us-east1-aiplatform.googleapis.com

Anda akan melihat sesuatu yang serupa (alamatnya akan berbeda). Perhatikan bahwa jalur ini menggunakan alamat IP publik karena API adalah API publik.

JANGAN DISALIN

; <<>> DiG 9.18.33-1~deb12u2-Debian <<>> us-east1-aiplatform.googleapis.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 58905
;; flags: qr rd ra; QUERY: 1, ANSWER: 14, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 65494
;; QUESTION SECTION:
;us-east1-aiplatform.googleapis.com. IN A

;; ANSWER SECTION:
us-east1-aiplatform.googleapis.com. 300 IN A    173.194.217.95
us-east1-aiplatform.googleapis.com. 300 IN A    172.217.204.95
us-east1-aiplatform.googleapis.com. 300 IN A    172.217.203.95
us-east1-aiplatform.googleapis.com. 300 IN A    142.250.98.95
us-east1-aiplatform.googleapis.com. 300 IN A    142.251.107.95
us-east1-aiplatform.googleapis.com. 300 IN A    74.125.196.95
us-east1-aiplatform.googleapis.com. 300 IN A    173.194.216.95
us-east1-aiplatform.googleapis.com. 300 IN A    108.177.11.95
us-east1-aiplatform.googleapis.com. 300 IN A    192.178.219.95
us-east1-aiplatform.googleapis.com. 300 IN A    173.194.210.95
us-east1-aiplatform.googleapis.com. 300 IN A    173.194.212.95
us-east1-aiplatform.googleapis.com. 300 IN A    173.194.215.95
us-east1-aiplatform.googleapis.com. 300 IN A    108.177.12.95
us-east1-aiplatform.googleapis.com. 300 IN A    74.125.26.95

4. Sekarang, mari kita lakukan pengujian ping cepat untuk melihat apakah kita dapat terhubung ke Gemini API. Perintah ini akan menggunakan 4 ping ke us-east1-aiplatform.googleapis.com sehingga kita akan mendapatkan respons dari alamat publik API.

ping -c 4 us-east1-aiplatform.googleapis.com

5. Kita akan kembali untuk menguji VM ini nanti. Tutup sesi SSH dan lanjutkan.

6. Tugas 4. Buat endpoint PSC ke googleapis dengan Terraform

Untuk mengaktifkan konektivitas pribadi ke endpoint Vertex API, kita akan membuat endpoint Private Service Connect untuk Google API. Hal ini akan memungkinkan kita menggunakan alamat IP pribadi yang kita tetapkan untuk merutekan traffic ke Google API yang kita butuhkan, dalam hal ini Vertex.

1. Buka Cloud Shell dalam tampilan editor jika belum terbuka. Kita akan membuat hal berikut:

• Buat IP untuk endpoint PSC 10.10.100.250 (resource "google_compute_global_address" "default")
• Membuat endpoint PSC ke Google API (resource "google_compute_global_forwarding_rule" "default")

Buka file psc.tf di folder terraform-build. Tambahkan kode berikut ke file.

Terraform psc.tf

resource "google_compute_global_address" "default" {
  name         = "gemini-ip"
  purpose      = "PRIVATE_SERVICE_CONNECT"
  network      = google_compute_network.default.id
  address_type = "INTERNAL"
  address      = "10.10.100.250"
}

resource "google_compute_global_forwarding_rule" "default" {  
  name                  = "pscgemini"
  target                = "all-apis"
  network               = google_compute_network.default.id
  ip_address            = google_compute_global_address.default.id
  load_balancing_scheme = ""
  }

2. Beralih ke terminal Cloud Shell, pastikan Anda berada di folder terraform-build. Kemudian, jalankan terraform init Lalu, jalankan terraform plan, yang akan menunjukkan bahwa 2 item akan ditambahkan,
   lalu jalankan terraform apply dan ketik yes untuk membuat endpoint IP dan PSC Google API.
3. Memverifikasi keberadaan endpoint

gcloud compute addresses list --filter="name=( 'gemini-ip' ...)"

gcloud compute forwarding-rules describe pscgemini --global

7. Tugas 5. Membuat entri DNS Manual ke googleapis dengan Terraform

Anda dapat membuat entri DNS manual untuk mengarah ke endpoint PSC menggunakan DNS pribadi. Tindakan ini akan memengaruhi semua jaringan yang Anda tetapkan ke perangkat tersebut.

1. Buka Layanan jaringan, lalu pilih Cloud DNS.
2. Di zona, Anda akan melihat zona yang dibuat secara otomatis untuk Private Service Connect untuk Google API, dengan jenis zona direktori layanan. Hal ini dapat digunakan untuk terhubung ke endpoint PSC dengan format **SERVICE-ENDPOINT.p.googleapis.com Contoh: aiplatform-pscgemini.p.googleapis.com
3. Dalam hal ini, kita ingin membuat entri DNS pribadi secara manual. Konfigurasinya adalah sebagai berikut

• Buat zona DNS pribadi bernama "googleapis-private" untuk "googleapis.com" dan batasi ke jaringan "python-net".
• Tambahkan catatan A untuk memetakan "googleapis.com" ke alamat IP "10.10.100.250".
• Tambahkan data CNAME untuk mengalihkan semua subdomain "googleapis.com" (misalnya, www.googleapis.com) ke "googleapis.com".

4. Buka Cloud Shell dalam tampilan editor jika belum terbuka. Buka file dns.tf di folder terraform-build. Tambahkan kode berikut ke file.

Terraform dns.tf

resource "google_dns_managed_zone" "private_zone" {
  name        = "googleapis-private"
  dns_name    = "googleapis.com."  
  visibility  = "private"
  project     = var.project_id     

  private_visibility_config {
    networks {
      network_url = google_compute_network.default.id  
    }
  }
}

resource "google_dns_record_set" "a_record" {
  name    = "googleapis.com."  
  type    = "A"
  ttl     = 300
  managed_zone = google_dns_managed_zone.private_zone.name
  project = var.project_id    

  rrdatas = ["10.10.100.250"]
}

resource "google_dns_record_set" "cname_record" {
 name    = "*.googleapis.com."
 type    = "CNAME"
 ttl     = 300
 managed_zone = google_dns_managed_zone.private_zone.name
 project = var.project_id    

 rrdatas = ["googleapis.com."]  
}

5. Beralih ke terminal Cloud Shell, pastikan Anda berada di folder terraform-build. Kemudian, jalankan terraform plan ini akan menunjukkan item yang akan ditambahkan,
   Kemudian, jalankan terraform apply dan ketik yes untuk membuat entri DNS pribadi.
6. Anda akan melihat penyiapan dengan data A dan CNAME seperti ini

7. Selanjutnya, kita akan memverifikasi konektivitas dengan perubahan ini di monitor-vm

8. Tugas 7. Memverifikasi konektivitas endpoint melalui alamat IP

Mari kita terhubung menggunakan endpoint pribadi untuk terhubung ke Gemini.

Catatan: Tidak ada konfigurasi manual yang diperlukan di VM.

1. Buka VM Instance monitor-vm. Pilih SSH dan SSH ke VM
2. Periksa jalur konektivitas ke us-east1-aiplatform.googleapis.com menggunakan perintah ping. Perintah ini akan melakukan ping ke alamat IP di DNS pribadi, data A untuk googleapis. IP ini adalah endpoint PSC dan ping Anda tidak akan berhasil.

ping -c 2 us-east1-aiplatform.googleapis.com

3. Periksa jalur konektivitas dengan ping menggunakan entri DNS yang dibuat secara otomatis untuk Google API PSC dengan aiplatform-pscvertexgemini.p.googleapis.com. Hal ini mengarah ke alamat IP endpoint PSC dan ping Anda akan gagal.

ping -c 2 aiplatform-pscgemini.p.googleapis.com

4. Periksa jalur konektivitas ke us-east1-aiplatform.googleapis.com menggunakan perintah dig. Alamat ini harus berupa alamat IP endpoint PSC (10.10.100.250).

dig us-east1-aiplatform.googleapis.com

5. Setelah selesai, Anda dapat menutup sesi SSH monitor-vm.
6. Sekarang kita dapat menjalankan TCP dump di cli-vm. Kita perlu membuka dua sesi SSH ke VM yang sama. Satu sesi akan menjalankan perintah tcpdump, sedangkan sesi lainnya akan menggunakan Gemini CLI.
7. SSH ke sesi pertama di cli-vm
8. Ketik perintah berikut untuk melihat konektivitas di tcpdump

sudo tcpdump -i any port 53 -n or host us-east1-aiplatform.googleapis.com

9. Sekarang, lakukan SSH ke sesi berikutnya di cli-vm
10. Aktifkan Gemini CLI dengan mengetik gemini
11. Ajukan pertanyaan berikut, apa warna langit untuk membuat panggilan ke Gemini API

12. Tekan enter untuk menjalankan dan melihat hasilnya.
13. Beralih kembali ke sesi pertama di cli-vm. Anda akan melihat hasil tcpdump. Anda akan melihat traffic masuk dan keluar, serta alamat IP VM menggunakan alamat IP endpoint PSC untuk terhubung ke gemini API

Tutup semua sesi SSH ke Instance VM

9. Pembersihan

1. Buka Cloud Shell, pastikan Anda berada di direktori terraform-build cd terraform-build, lalu jalankan perintah berikut terraform destroy dan ketik yes, semua resource yang Anda buat di project dengan Terraform akan dihapus.

10. Selamat

Selamat, Anda telah berhasil terhubung ke Gemini CLI menggunakan alamat API publik dan secara pribadi menggunakan Endpoint Private Service Connect untuk Google API. Fungsi ini dapat memperluas konektivitas API pribadi ke lingkungan cloud/lokal Anda yang terhubung melalui (Interconnect, Cross-Cloud Interconnect, dan VPC).

Langkah berikutnya/Pelajari lebih lanjut

Anda dapat membaca lebih lanjut jaringan Vertex AI dan melihat repo Gemini CLI

Ikuti lab berikutnya

Lanjutkan quest Anda dengan Google Cloud, dan pelajari lab Google Cloud lainnya:

• Dasar-Dasar Jaringan di Google Cloud
• Penjelajah AI Generatif - Vertex AI
• Tur Cloud Networking