Bu sayfa, Cloud Translation API ile çevrilmiştir.

Private Service Connect uç noktası olan GCE'de Gemini CLI

1. Genel Bakış

Gemini CLI'yı hem yerel hem de sanal ortamlarınızda kullanabilirsiniz. Gemini CLI, Gemini'ın gücünü doğrudan terminalinize getiren açık kaynaklı bir yapay zeka aracısıdır. Ağ oluşturma açısından, Gemini CLI'yı kullandığınızda herkese açık olarak erişilebilen API IP adresi üzerinden Gemini API'ye bir çağrı yapılır.

Peki Google Compute Engine makinesinde Gemini CLI'yı kullanmak istiyorsanız ancak API'ye özel olarak bağlanmak istiyorsanız ne olur? Bu codelab'de, trafiği belirttiğiniz bir dahili IP adresine yönlendirmek için Google API'leri ile Private Service Connect uç noktasını nasıl yapılandıracağınızı göreceksiniz.

Yapılandırmalar Terraform, gcloud ve konsolun bir kombinasyonu olacaktır.

Bu laboratuvarda aşağıdaki görevi nasıl gerçekleştireceğinizi öğreneceksiniz:

Sanal makine örneği ve Cloud NAT'yi ayarlama
Gemini CLI'yı yükleme ve kimlik doğrulama
Googleapis'e bağlanmak için Private Service Connect uç noktasını yapılandırma
*.googleais ile bağlantı yolunu doğrulayın
Manuel DNS girişlerini yapılandırma

Bu laboratuvarda aşağıdaki kalıbı oluşturacaksınız.

Şekil 1.

2. Google Cloud hizmetlerinin kurulumu

Kendi hızınızda ortam kurulumu

Google Cloud Console'da oturum açın ve yeni bir proje oluşturun veya mevcut bir projeyi yeniden kullanın. Henüz bir Gmail veya Google Workspace hesabınız yoksa oluşturmanız gerekir.

Proje adı, bu projenin katılımcıları için görünen addır. Google API'leri tarafından kullanılmayan bir karakter dizesidir. Bu bilgiyi istediğiniz zaman güncelleyebilirsiniz.
Proje kimliği, tüm Google Cloud projelerinde benzersizdir ve sabittir (ayarlandıktan sonra değiştirilemez). Cloud Console, benzersiz bir dizeyi otomatik olarak oluşturur. Genellikle bu dizenin ne olduğuyla ilgilenmezsiniz. Çoğu codelab'de proje kimliğinize (genellikle PROJECT_ID olarak tanımlanır) başvurmanız gerekir. Oluşturulan kimliği beğenmezseniz başka bir rastgele kimlik oluşturabilirsiniz. Dilerseniz kendi adınızı deneyerek kullanılabilir olup olmadığını kontrol edebilirsiniz. Bu adım tamamlandıktan sonra değiştirilemez ve proje süresince geçerli kalır.
Bazı API'lerin kullandığı üçüncü bir değer olan Proje Numarası da vardır. Bu üç değer hakkında daha fazla bilgiyi belgelerde bulabilirsiniz.

Ardından, Cloud kaynaklarını/API'lerini kullanmak için Cloud Console'da faturalandırmayı etkinleştirmeniz gerekir. Bu codelab'i tamamlamak neredeyse hiç maliyetli değildir. Bu eğitimin ötesinde faturalandırılmayı önlemek için kaynakları kapatmak üzere oluşturduğunuz kaynakları veya projeyi silebilirsiniz. Yeni Google Cloud kullanıcıları 300 ABD doları değerinde ücretsiz deneme programından yararlanabilir.

Cloud Shell'i başlatma

Google Cloud, dizüstü bilgisayarınızdan uzaktan çalıştırılabilir. Ancak bu codelab'de, Cloud'da çalışan bir komut satırı ortamı olan Google Cloud Shell'i kullanacaksınız.

Google Cloud Console'da sağ üstteki araç çubuğunda Cloud Shell simgesini tıklayın:

Ortamın sağlanması ve bağlantının kurulması yalnızca birkaç saniye sürer. İşlem tamamlandığında aşağıdakine benzer bir sonuç görürsünüz:

Bu sanal makine, ihtiyaç duyacağınız tüm geliştirme araçlarını içerir. 5 GB boyutunda kalıcı bir ana dizin sunar ve Google Cloud üzerinde çalışır. Bu sayede ağ performansı ve kimlik doğrulama önemli ölçüde iyileştirilir. Bu codelab'deki tüm çalışmalarınızı tarayıcıda yapabilirsiniz. Herhangi bir şey yüklemeniz gerekmez.

3. 1. görev: Terraform ile ortamı ayarlama

Güvenlik duvarı kuralları ve alt ağ içeren özel bir VPC oluşturacağız. Cloud Console'u açın ve kullanacağınız projeyi seçin.

Konsolunuzun sağ üst kısmında bulunan Cloud Shell'i açın, Cloud Shell'de doğru proje kimliğini gördüğünüzden emin olun ve erişime izin vermek için tüm istemleri onaylayın.
terraform-build adlı bir klasör oluşturun ve bu klasöre gidin.

mkdir terraform-build  && cd terraform-build

main.tf ve variable.tf dosyası oluşturun.

touch main.tf variable.tf

Cloud Shell Düzenleyici görünümüne geçin. Düzenleyici'yi seçin ve arayüzün yüklenebilmesi için gerekli tüm istemlere izin verin.
Yüklendikten sonra File > Open Folder'a (Dosya > Klasörü Aç) gidin ve /home/your-user-name/terraform-build'a gidip Ok'u (Tamam) seçerek klasörü düzenleyicide açın.
variable.tf dosyasını seçin ve aşağıdakileri ekleyin. your-project-id-here metnini, tırnak işaretleri içinde gerçek proje kimliğinizle değiştirin.

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

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

Ardından main.tf dosyasını açın. Aşağıda açıklandığı gibi çeşitli işlemleri gerçekleştirmek için bazı Terraform kodları ekleyeceğiz.

*API'leri etkinleştirme*	`resource` `"google_project_service"` `"default"`
*python-net adlı VPC'yi oluşturun*	`resource` `"google_compute_network"` `"default"`
*Alt ağ ekleme*	`resource` `"google_compute_subnetwork"` `"default"`
*İki güvenlik duvarı kuralı ekleme*	`resource` `"google_compute_firewall"` `"allow_icmp"resource` `"google_compute_firewall"` `"allow_ssh"`

Aşağıdakileri kopyalayıp main .tf dosyasına yapıştırın.

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"]
}

Cloud Shell terminaline geri dönün, terraform-build dizininde olduğunuzdan emin olun cd terraform-build ve aşağıdaki komutları çalıştırın.

terraform init

Çalışma dizinini başlatır. Bu adımda, belirli yapılandırma için gerekli sağlayıcılar indirilir.

terraform plan

Terraform'un altyapınızı dağıtmak için hangi işlemleri yapacağını gösteren bir yürütme planı oluşturur.

Şimdi kaynakları oluşturmak için terraform apply komutunu çalıştırın ve çalıştırmak için yes yazın.

4. 2. görev: Terraform ile NAT ağ geçidi ve VM oluşturma

İnternete giden harici erişim izni vermemiz gerekiyor. Bu nedenle, bir Cloud NAT ağ geçidi oluşturup ekleyelim.

Cloud Shell'i açın, terraform-build klasörüne gidin ve aşağıdaki dosyaları oluşturun (toplam üç dosya). Bunları daha sonra düzenleyeceğiz.

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

Cloud Shell düzenleyici görünümüne geçin, nat-vm.tf dosyasını seçin ve aşağıdaki Terraform kodunu ekleyin. Bu işlem, bir NAT ağ geçidi ve iki sanal makine oluşturur.

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
}

Cloud Shell terminaline geçin, terraform-build klasöründe olduğunuzdan emin olun ve terraform plan komutunu çalıştırın. Bu komut, 4 öğenin ekleneceğini gösterir. Ardından terraform apply komutunu çalıştırın ve NAT ağ geçidini ve iki sanal makineyi oluşturmak için yes yazın.

5. 3. görev: KSA sanal makinelerini yapılandırma ve test etme

Sanal makine örneklerine gidin. cli-vm ile başlayan sanal makineyi seçin. SSH'yi seçin.
SSH'yi kullandığınızda sanal makineye erişebilirsiniz. Gemini CLI'yi çalıştırırken kullanmak üzere bir klasör oluşturalım.

mkdir geminicli && cd geminicli

Gemini CLI'yı yüklemek için Node.js gerekir. Aşağıdaki komutları kullanarak Node.js'yi yükleyin.

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

Komut dosyasını çalıştır

sudo -E bash nodesource_setup.sh

Node.js'yi yükleyin

sudo apt-get install -y nodejs

Daha sonra bazı testler yapmak için Vertex AI kimlik doğrulama seçeneğini kullanarak kimlik doğrulamaya yardımcı olacak bazı değişkenler ayarlayalım. Not: YOUR_PROJECT_ID yerine gerçek project ID değerinizi girin.

cat <<EOF >> ~/.bashrc 

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

Reload bash

source ~/.bashrc

Şimdi kimlik doğrulama işlemine geçelim. Sanal makinede aşağıdaki komutu çalıştırın ve istendiğinde y tuşuna basın.

gcloud auth application-default login

Ardından, https:// ile başlayan URL'yi kopyalayın, laboratuvar tarayıcı pencerenizde yeni bir sekme açın ve URL'yi yapıştırın. İstemleri kabul edin.
Aşağıdakileri gördüğünüzde kopyala'yı seçin, sanal makine cli-vm oturumuna geri dönün ve Enter authorization code: (Yetkilendirme kodunu girin:) için kopyaladığınız kodu yapıştırıp kimlik doğrulamak üzere Enter tuşuna basın.

Şimdi Gemini CLI'yi yükleyelim ve komutu çalıştıralım.

sudo npm install -g @google/gemini-cli

İşlem tamamlandıktan sonra gemini yazarak arayüzü başlatın, tercih ettiğiniz temayı seçin ve Select Auth method (Kimlik doğrulama yöntemini seçin) bölümünde Vertex AI simgesini tıklayın.

Kimliğiniz doğrulandıktan sonra Gemini CLI'yı kullanmaya başlayabilirsiniz.

İzleme VM'si aracılığıyla Gemini'a giden trafik rotasını izleme

Sanal makine örneklerine gidin. monitor-vm ile başlayan VM'yi seçin. SSH'yi seçin.
monitor-vm'ye SSH ile bağlandıktan sonra erişiminiz olur.
Gemini API'ye bağlantı yolunu test etmek için dig komutunu kullanalım. us-east1-aiplatform.googleapis.com adresini kullanacağız.

dig us-east1-aiplatform.googleapis.com

Buna benzer bir şey görmelisiniz (adres farklı olacaktır). API herkese açık bir API olduğundan yolun herkese açık IP adresleri üzerinden olduğunu unutmayın.

KOPYALAMAYIN

; <<>> 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

Şimdi Gemini API'ye bağlanıp bağlanamadığımızı görmek için hızlı bir ping testi yapalım. Bu komut, us-east1-aiplatform.googleapis.com adresine 4 ping gönderir. Böylece API'nin herkese açık adresinden yanıt alırız.

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

Bu sanal makineyi daha sonra test edeceğiz. SSH oturumunu kapatıp devam edelim.

6. 4. görev: Terraform ile googleapis için PSC uç noktası oluşturma

Vertex API uç noktamıza özel bağlantıyı etkinleştirmek için Google API'leri için bir Private Service Connect uç noktası oluşturacağız. Bu sayede, trafiği ihtiyacımız olan Google API'lerine (bu örnekte Vertex) yönlendirmek için atadığımız özel bir IP adresini kullanabiliriz.

Henüz açık değilse Cloud Shell'i düzenleyici görünümünde açın. Aşağıdakileri oluşturacağız:

PSC uç noktası 10.10.100.250 için bir IP oluşturun (resource "google_compute_global_address" "default")
Google API'leri için PSC uç noktası oluşturma (resource "google_compute_global_forwarding_rule" "default")

terraform-build klasöründeki psc.tf dosyasını açın. Aşağıdaki kodu dosyaya ekleyin.

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 = ""
  }

Cloud Shell terminaline geçin ve terraform-build klasöründe olduğunuzdan emin olun. Ardından terraform init komutunu çalıştırın. Bu komut,2 öğenin ekleneceğini gösterir.
Ardından terraform apply komutunu çalıştırın ve IP ile PSC Google API'leri uç noktasını oluşturmak için yes yazın.terraform plan
Uç noktanın varlığını doğrulama

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

gcloud compute forwarding-rules describe pscgemini --global

7. 5. görev: Terraform ile googleapis için manuel DNS girişi oluşturma

Özel DNS kullanarak PSC uç noktasına yönlendiren manuel bir DNS girişi oluşturabilirsiniz. Bu durum, atadığınız tüm ağları etkiler.

Ağ hizmetleri'ne gidin ve Cloud DNS'yi seçin.
Bölgelerde, Google API'leri için Private Service Connect'e yönelik otomatik olarak oluşturulmuş bir bölge görürsünüz. Bu bölgenin türü hizmet dizinidir. Bu, **SERVICE-ENDPOINT.p.googleapis.com biçiminde PSC uç noktasına bağlanmak için kullanılabilir. Örnek: aiplatform-pscgemini.p.googleapis.com
Bu durumda, özel bir DNS girişini manuel olarak oluşturmak istiyoruz. Yapılandırma şu şekilde olur:

"googleapis.com" için "googleapis-private" adlı özel bir DNS bölgesi oluşturun ve bunu "python-net" ağıyla sınırlayın.
"googleapis.com"u "10.10.100.250" IP adresine eşlemek için bir A kaydı ekleyin.
"googleapis.com" alanının tüm alt alanlarını (ör. www.googleapis.com) "googleapis.com" alanına yönlendirmek için bir CNAME kaydı ekleyin.

Henüz açık değilse Cloud Shell'i düzenleyici görünümünde açın. terraform-build klasöründeki dns.tf dosyasını açın. Aşağıdaki kodu dosyaya ekleyin.

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."]  
}

Cloud Shell terminaline geçin ve terraform-build klasöründe olduğunuzdan emin olun. Ardından terraform plan komutunu çalıştırın. Bu komut,hangi öğelerin ekleneceğini gösterir.
Ardından terraform apply komutunu çalıştırın ve özel DNS girişi oluşturmak için yes yazın.
Şu şekilde bir A kaydı ve CNAME içeren kurulum görmelisiniz:

Ardından, monitor-vm üzerinde bu değişikliklerle bağlantıyı doğruluyoruz.

8. 7. görev: IP adresi üzerinden uç nokta bağlantısını doğrulama

Gemini'a bağlanmak için özel uç noktayı kullanarak bağlanalım.

Sanal makine örneği monitor-vm'ye gidin. SSH'yi seçin ve sanal makineye SSH üzerinden bağlanın.
ping komutunu kullanarak us-east1-aiplatform.googleapis.com adresine giden bağlantı yolunu kontrol edin. Bu işlem, googleapis için özel DNS'deki IP adresine A kaydı ping'i gönderir. Bu IP bir PSC uç noktasıdır ve ping işlemleriniz başarısız olur.

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

aiplatform-pscvertexgemini.p.googleapis.com ile PSC Google API'leri için otomatik olarak oluşturulan DNS girişini kullanarak ping ile bağlantı yolunu kontrol edin. Bu, PSC uç noktasının IP adresini gösterir ve ping işlemleriniz başarısız olur.

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

dig komutunu kullanarak us-east1-aiplatform.googleapis.com adresine giden bağlantı yolunu kontrol edin. Bu, PSC uç noktasının IP adresi (10.10.100.250) olmalıdır.

dig us-east1-aiplatform.googleapis.com

İşlem tamamlandıktan sonra monitor-vm SSH oturumunu kapatabilirsiniz.
Artık cli-vm üzerinde TCP dökümü çalıştırabiliriz. Aynı VM'ye iki SSH oturumu açmamız gerekir. Bir oturumda tcpdump komutu çalıştırılacak, diğerinde ise Gemini KSA'sı kullanılacak.
cli-vm'de ilk oturuma SSH bağlayın.
Bağlantıyı tcpdump'ta görmek için aşağıdaki komutu yazın.

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

Şimdi cli-vm üzerinde sonraki oturuma SSH üzerinden bağlanın.
gemini yazarak Gemini KSA'yı etkinleştirin.
Gemini API'ye çağrı oluşturmak için "Gökyüzü ne renk?" sorusunu sorun.

Çalıştırmak ve sonucu görmek için Enter tuşuna basın.
cli-vm'de ilk oturuma geri dönün. tcpdump'ın sonucunu görmeniz gerekir. Giriş ve çıkış trafiğinin yanı sıra sanal makinenin IP adresinin, Gemini API'ye bağlanmak için PSC uç noktası IP adresini kullandığını fark edeceksiniz.

Sanal makine örnekleriyle tüm SSH oturumlarını kapatın.

9. Temizleme

Cloud Shell'e gidin, cd terraform-build terraform-build dizininde olduğunuzdan emin olun terraform destroy ve aşağıdaki komutu çalıştırın yes. Terraform ile projenizde oluşturduğunuz tüm kaynaklar kaldırılacaktır.

10. Tebrikler

Tebrikler, hem genel API adresini kullanarak hem de Google API'leri için Private Service Connect uç noktasını kullanarak Gemini CLI'ye başarıyla bağlandınız. Bu işlev, özel API bağlantısını (Interconnect, Cross-Cloud Interconnect ve VPC) aracılığıyla bağlanan şirket içi/diğer bulut ortamınıza genişletebilir.

Sonraki adımlar / Daha fazla bilgi

Vertex AI ağ iletişimi hakkında daha fazla bilgi edinebilir ve Gemini CLI deposuna göz atabilirsiniz.

Sonraki laboratuvarınıza katılın

Google Cloud ile görevinize devam edin ve aşağıdaki Google Cloud laboratuvarlarına göz atın: