Gemini CLI su GCE con un endpoint Private Service Connect

1. Panoramica

Puoi utilizzare l'interfaccia a riga di comando Gemini sia nell'ambiente locale sia in quello virtuale. Gemini CLI è un agente AI open source che porta la potenza di Gemini direttamente nel tuo terminale. Dal punto di vista del networking, quando utilizzi la CLI Gemini, viene effettuata una chiamata all'API Gemini tramite l'indirizzo IP dell'API, che è accessibile pubblicamente.

Cosa succede se vuoi utilizzare Gemini CLI su una macchina Google Compute Engine, ma vuoi connetterti all'API in modo privato? In questo codelab vedrai come configurare l'endpoint Private Service Connect per le API di Google, in modo da indirizzare il traffico a un indirizzo IP interno che specifichi.

Le configurazioni saranno una combinazione di Terraform, gcloud e console.

In questo lab imparerai a svolgere le seguenti attività:

• Configura l'istanza VM e Cloud NAT
• Installa l'interfaccia a riga di comando Gemini e autenticati
• Configura l'endpoint Private Service Connect per connetterti a Googleapis
• Verifica il percorso di connettività a *.googleais
• Configurare le voci DNS manuali

In questo lab creerai il seguente pattern.

Figura 1.

2. Configurazione dei servizi Google Cloud

Configurazione dell'ambiente autonoma

1. Accedi alla console Google Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai già un account Gmail o Google Workspace, devi crearne uno.

• Il nome del progetto è il nome visualizzato per i partecipanti a questo progetto. È una stringa di caratteri non utilizzata dalle API di Google. Puoi sempre aggiornarlo.
• L'ID progetto è univoco in tutti i progetti Google Cloud ed è immutabile (non può essere modificato dopo l'impostazione). La console Cloud genera automaticamente una stringa univoca, di solito non ti interessa di cosa si tratta. Nella maggior parte dei codelab, dovrai fare riferimento all'ID progetto (in genere identificato come PROJECT_ID). Se non ti piace l'ID generato, puoi generarne un altro casuale. In alternativa, puoi provare a crearne uno e vedere se è disponibile. Non può essere modificato dopo questo passaggio e rimane per tutta la durata del progetto.
• Per tua informazione, esiste un terzo valore, un numero di progetto, utilizzato da alcune API. Scopri di più su tutti e tre questi valori nella documentazione.

Attenzione:un ID progetto è univoco a livello globale e non può essere utilizzato da nessun altro dopo che lo hai selezionato. Sei l'unico utente di questo ID. Anche se un progetto viene eliminato, l'ID non può essere riutilizzato

Nota:se utilizzi un account Gmail, puoi lasciare la posizione predefinita impostata su Nessuna organizzazione. Se utilizzi un account Google Workspace, scegli una posizione adatta alla tua organizzazione.

2. Successivamente, devi abilitare la fatturazione in Cloud Console per utilizzare le risorse/API Cloud. Completare questo codelab non costa molto, se non nulla. Per arrestare le risorse ed evitare addebiti oltre a quelli previsti da questo tutorial, puoi eliminare le risorse che hai creato o il progetto. I nuovi utenti di Google Cloud possono beneficiare del programma prova senza costi di 300$.

Avvia Cloud Shell

Sebbene Google Cloud possa essere gestito da remoto dal tuo laptop, in questo codelab utilizzerai Google Cloud Shell, un ambiente a riga di comando in esecuzione nel cloud.

Nella console Google Cloud, fai clic sull'icona di Cloud Shell nella barra degli strumenti in alto a destra:

Bastano pochi istanti per eseguire il provisioning e connettersi all'ambiente. Al termine, dovresti vedere un risultato simile a questo:

Questa macchina virtuale è caricata con tutti gli strumenti di sviluppo di cui avrai bisogno. Offre una home directory permanente da 5 GB e viene eseguita su Google Cloud, migliorando notevolmente le prestazioni di rete e l'autenticazione. Tutto il lavoro in questo codelab può essere svolto all'interno di un browser. Non devi installare nulla.

3. Attività 1: Configura l'ambiente con Terraform

Creeremo un VPC personalizzato con regole firewall e subnet. Apri la console Cloud e seleziona il progetto che utilizzerai.

1. Apri Cloud Shell in alto a destra nella console, assicurati di visualizzare l'ID progetto corretto in Cloud Shell e conferma le richieste per consentire l'accesso.
2. Crea una cartella denominata terraform-build e spostati al suo interno

mkdir terraform-build  && cd terraform-build

3. Crea un file main.tf e variable.tf.

touch main.tf variable.tf 

4. Passa alla visualizzazione dell'editor di Cloud Shell. Seleziona Editor e assicurati di consentire tutti i prompt necessari per caricare l'interfaccia.
5. Una volta caricato, vai a File > Apri cartella e vai a /home/your-user-name/terraform-build e seleziona Ok per aprire la cartella nell'editor.
6. Seleziona il file variable.tf e aggiungi quanto segue. Sostituisci il testo your-project-id-here con l'ID progetto effettivo tra virgolette.

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

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

7. A questo punto, apri il file main.tf. Aggiungeremo del codice Terraform per eseguire varie azioni, come spiegato di seguito.

Abilita le API	resource "google_project_service" "default"
Crea un VPC chiamato python-net	resource "google_compute_network" "default"
Aggiungere una subnet	resource "google_compute_subnetwork" "default"
Aggiungi due regole firewall	resource "google_compute_firewall" "allow_icmp"resource "google_compute_firewall" "allow_ssh"

8. Copia e incolla quanto segue nel 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. Torna al terminale Cloud Shell, assicurati di trovarti nella directory terraform-build cd terraform-build ed esegui questi comandi:

terraform init

Inizializza la directory di lavoro. Questo passaggio scarica i provider richiesti per la configurazione specificata.

terraform plan

Genera un piano di esecuzione, che mostra le azioni che Terraform eseguirà per eseguire il deployment dell'infrastruttura.

10. Ora, per creare le risorse, esegui il comando terraform apply e digita yes per eseguirlo.

Verifica la configurazione:controlla il tuo ambiente per

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

4. Attività 2: Crea gateway NAT e VM con Terraform

Dobbiamo concedere l'accesso esterno in uscita a internet, quindi creiamo un gateway Cloud NAT e lo colleghiamo.

1. Apri Cloud Shell, vai alla cartella terraform-build e crea i seguenti file (tre in totale). Li modificheremo in un secondo momento.

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

2. Passa alla visualizzazione Editor di Cloud Shell, seleziona il file nat-vm.tf e aggiungi il seguente codice Terraform. Verrà creato un gateway NAT e due 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. Passa al terminale Cloud Shell, assicurati di trovarti nella cartella terraform-build ed esegui terraform plan. Verrà visualizzato che verranno aggiunti 4 elementi, quindi esegui terraform apply e digita yes per creare il gateway NAT e due VM.

Verifica la configurazione:controlla il tuo ambiente per

1 gateway NAT

1 router Cloud

VM denominata cli-vm

VM denominata monitor-vm

5. Attività 3: Configura le VM CLI e testa

1. Vai a Istanze VM. Seleziona la VM che inizia con cli-vm. Scegli SSH.
2. Una volta eseguito l'accesso SSH, dovresti avere accesso alla VM. Creiamo una cartella per quando eseguiamo la CLI Gemini.

mkdir geminicli && cd geminicli

3. Per installare Gemini CLI, è necessario Node.js. Installa Node.js utilizzando il seguente comando

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

Esegui script

sudo -E bash nodesource_setup.sh

Installa Node.js

sudo apt-get install -y nodejs

4. Impostiamo alcune variabili che ci aiuteranno a utilizzare l'opzione di autenticazione di Vertex AI per autenticare questa operazione e fare alcuni test in un secondo momento. P.S. Sostituisci YOUR_PROJECT_ID con il tuo project ID effettivo

cat <<EOF >> ~/.bashrc 

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

Ricarica bash

source ~/.bashrc

5. Ora eseguiamo l'autenticazione. Esegui questo comando nella VM e premi y quando richiesto.

gcloud auth application-default login

6. Copia quindi l'URL che inizia con https://, apri una nuova scheda nella finestra del browser del lab e incolla l'URL. Accetta le richieste.
7. Quando vedi il seguente messaggio, seleziona Copia, torna alla sessione cli-vm della VM e, per Inserisci codice di autorizzazione, incolla il codice che hai copiato e premi Invio per eseguire l'autenticazione.

8. Ora installiamo Gemini CLI eseguendo il comando

sudo npm install -g @google/gemini-cli

Una volta completata la digitazione di gemini per avviare l'interfaccia, seleziona un tema che preferisci e scegli Vertex AI in Seleziona metodo di autenticazione.

9. Una volta autenticato, puoi iniziare a utilizzare Gemini CLI

Nota:puoi modificare la domanda del prompt.

Monitorare il percorso del traffico verso Gemini tramite monitor vm

1. Vai a Istanze VM. Seleziona la VM che inizia con monitor-vm. Scegli SSH.
2. Una volta eseguito l'accesso SSH a monitor-vm, dovresti avere accesso
3. Utilizziamo il comando dig per testare il percorso di connessione all'API Gemini. Utilizzeremo us-east1-aiplatform.googleapis.com

dig us-east1-aiplatform.googleapis.com

Dovresti visualizzare un risultato simile (l'indirizzo sarà diverso). Tieni presente che il percorso avviene tramite indirizzi IP pubblici, poiché l'API è un'API pubblica.

NON COPIARE

; <<>> 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. Ora eseguiamo un rapido test ping per verificare se riusciamo a connetterci all'API Gemini. Questo comando utilizzerà 4 ping per us-east1-aiplatform.googleapis.com, quindi riceveremo una risposta dall'indirizzo pubblico dell'API.

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

5. Torneremo a testare questa VM in un secondo momento. Chiudi la sessione SSH e continuiamo.

6. Attività 4: Crea l'endpoint PSC per googleapis con Terraform

Per abilitare la connettività privata al nostro endpoint API Vertex, creeremo un endpoint Private Service Connect per le API di Google. In questo modo potremo utilizzare un indirizzo IP privato che assegniamo per indirizzare il traffico alle API di Google di cui abbiamo bisogno, in questo caso Vertex.

1. Apri Cloud Shell nella visualizzazione dell'editor, se non è già aperta. Creeremo quanto segue:

• Crea un IP per l'endpoint PSC 10.10.100.250 (resource "google_compute_global_address" "default")
• Crea un endpoint PSC per le API di Google (resource "google_compute_global_forwarding_rule" "default")

Apri il file psc.tf nella cartella terraform-build. Aggiungi il seguente codice al 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. Passa al terminale Cloud Shell e assicurati di trovarti nella cartella terraform-build. Quindi esegui terraform init,poi terraform plan. Verrà visualizzato che verranno aggiunti due elementi.
   Quindi esegui terraform apply e digita yes per creare l'endpoint IP e PSC delle API di Google.
3. Verifica l'esistenza dell'endpoint

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

gcloud compute forwarding-rules describe pscgemini --global

7. Attività 5: Crea una voce DNS manuale per googleapis con Terraform

Puoi creare una voce DNS manuale che punti all'endpoint PSC utilizzando il DNS privato. Ciò influirà su tutte le emittenti che gli assegni.

1. Vai a Servizi di rete e seleziona Cloud DNS.
2. Nelle zone dovresti vedere una zona creata automaticamente per Private Service Connect per le API di Google, con il tipo di zona Service Directory. Può essere utilizzato per connettersi all'endpoint PSC con il formato **SERVICE-ENDPOINT.p.googleapis.com. Esempio: aiplatform-pscgemini.p.googleapis.com
3. In questo caso, vogliamo creare manualmente una voce DNS privata. La configurazione sarà la seguente

• Crea una zona DNS privata denominata "googleapis-private" per "googleapis.com" e limitane l'accesso alla rete "python-net".
• Aggiungi un record A per mappare "googleapis.com" all'indirizzo IP "10.10.100.250".
• Aggiungi un record CNAME per reindirizzare tutti i sottodomini di "googleapis.com" (ad es. www.googleapis.com) a "googleapis.com".

4. Apri Cloud Shell nella visualizzazione dell'editor, se non è già aperta. Apri il file dns.tf nella cartella terraform-build. Aggiungi il seguente codice al 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. Passa al terminale Cloud Shell e assicurati di trovarti nella cartella terraform-build. Poi esegui terraform plan,che ti mostrerà gli elementi che verranno aggiunti.
   Poi esegui terraform apply e digita yes per creare la voce DNS privata.
6. Dovresti visualizzare una configurazione con un record A e un record CNAME come questo

7. Successivamente, verifichiamo la connettività con queste modifiche su monitor-vm

8. Attività 7: Verifica la connettività dell'endpoint tramite l'indirizzo IP

Connettiamoci utilizzando l'endpoint privato per connetterci a Gemini.

Nota:non sono necessarie configurazioni manuali sulla VM.

1. Vai all'istanza VM monitor-vm. Seleziona SSH e accedi alla VM tramite SSH
2. Controlla il percorso di connettività a us-east1-aiplatform.googleapis.com utilizzando il comando ping. Verrà eseguito il ping dell'indirizzo IP nel DNS privato, record A per googleapis. Questo IP è un endpoint PSC e i ping non andranno a buon fine.

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

3. Controlla il percorso di connettività con un ping utilizzando la voce DNS creata automaticamente per le API di Google PSC con aiplatform-pscvertexgemini.p.googleapis.com. Questo punta all'indirizzo IP dell'endpoint PSC e i ping non andranno a buon fine.

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

4. Controlla il percorso di connettività a us-east1-aiplatform.googleapis.com utilizzando il comando dig. Deve essere l'indirizzo IP dell'endpoint PSC (10.10.100.250).

dig us-east1-aiplatform.googleapis.com

5. Al termine, puoi chiudere la sessione SSH di monitor-vm.
6. Ora possiamo eseguire un dump TCP sulla cli-vm. Dobbiamo aprire due sessioni SSH nella stessa VM. Una sessione eseguirà il comando tcpdump, l'altra utilizzerà la CLI di Gemini.
7. Accedi tramite SSH alla prima sessione su cli-vm
8. Digita il seguente comando per visualizzare la connettività in un tcpdump

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

9. Ora accedi alla sessione successiva tramite SSH su cli-vm
10. Attiva la CLI Gemini digitando gemini
11. Poni la seguente domanda: di che colore è il cielo? per generare una chiamata all'API Gemini

12. Premi Invio per eseguire il comando e visualizzare il risultato.
13. Torna alla prima sessione su cli-vm. Dovresti vedere il risultato di tcpdump. Noterai che l'indirizzo IP della VM utilizza l'indirizzo IP dell'endpoint PSC per connettersi all'API Gemini

Chiudi tutte le sessioni SSH alle istanze VM

9. Esegui la pulizia

1. Vai a Cloud Shell, assicurati di trovarti nella directory terraform-build cd terraform-build ed esegui il comando seguente terraform destroy e digita yes tutte le risorse che hai creato nel tuo progetto con Terraform verranno rimosse.

10. Complimenti

Congratulazioni, hai eseguito la connessione a Gemini CLI utilizzando sia l'indirizzo API pubblico sia in modalità privata utilizzando l'endpoint Private Service Connect per le API di Google. Questa funzionalità può estendere la connettività API privata al tuo ambiente on-premise/altro cloud connesso tramite (Interconnect, Cross-Cloud Interconnect e VPC).

Prossimi passi/Scopri di più

Puoi leggere di più sul networking di Vertex AI e consultare il repository dell'interfaccia a riga di comando Gemini.

Segui il prossimo lab

Continua la Quest con Google Cloud e dai un'occhiata a questi altri lab Google Cloud:

• Networking Fundamentals in Google Cloud
• Generative AI Explorer - Vertex AI
• Tour di Cloud Networking