CLI de Gemini en GCE con un extremo de Private Service Connect

1. Descripción general

Puedes usar la CLI de Gemini en tus entornos locales y virtuales. Gemini CLI es un agente de IA de código abierto que lleva el poder de Gemini directamente a tu terminal. Desde el punto de vista de las redes, cuando usas la CLI de Gemini, se realiza una llamada a la API de Gemini a través de la dirección IP de la API, que es de acceso público.

¿Qué sucede si quieres usar la CLI de Gemini en una máquina de Google Compute Engine, pero quieres conectarte a la API de forma privada? En estos codelabs, verás cómo configurar el extremo de Private Service Connect para las APIs de Google y cómo enrutar el tráfico a una dirección IP interna que especifiques.

Las configuraciones serán una combinación de Terraform, gcloud y la consola.

En este lab, aprenderás a realizar la siguiente tarea:

• Configura la instancia de VM y Cloud NAT
• Instala Gemini CLI y autentícate
• Configura el extremo de Private Service Connect para conectarte a Googleapis
• Verifica la ruta de conectividad a *.googleais
• Configura entradas de DNS manuales

En este lab, crearás el siguiente patrón.

Figura 1.

2. Configuración de los servicios de Google Cloud

Configuración del entorno de autoaprendizaje

1. Accede a Google Cloud Console y crea un proyecto nuevo o reutiliza uno existente. Si aún no tienes una cuenta de Gmail o de Google Workspace, debes crear una.

• El Nombre del proyecto es el nombre visible de los participantes de este proyecto. Es una cadena de caracteres que no se utiliza en las APIs de Google. Puedes actualizarla cuando quieras.
• El ID del proyecto es único en todos los proyectos de Google Cloud y es inmutable (no se puede cambiar después de configurarlo). La consola de Cloud genera automáticamente una cadena única. Por lo general, no importa cuál sea. En la mayoría de los codelabs, deberás hacer referencia al ID de tu proyecto (suele identificarse como PROJECT_ID). Si no te gusta el ID que se generó, podrías generar otro aleatorio. También puedes probar uno propio y ver si está disponible. No se puede cambiar después de este paso y se usa el mismo durante todo el proyecto.
• Recuerda que hay un tercer valor, un número de proyecto, que usan algunas APIs. Obtén más información sobre estos tres valores en la documentación.

Precaución: El ID del proyecto es único a nivel global y no lo puede usar nadie más después de que lo hayas seleccionado. Eres el único usuario de ese ID. Incluso si se borra un proyecto, no se puede volver a usar el ID.

Nota: Si usas una cuenta de Gmail, puedes dejar la ubicación predeterminada como Sin organización. Si usas una cuenta de Google Workspace, elige una ubicación adecuada para tu organización.

2. A continuación, deberás habilitar la facturación en la consola de Cloud para usar las APIs o los recursos de Cloud. Ejecutar este codelab no costará mucho, tal vez nada. Para cerrar recursos y evitar que se generen cobros más allá de este instructivo, puedes borrar los recursos que creaste o borrar el proyecto. Los usuarios nuevos de Google Cloud son aptos para participar en el programa Prueba gratuita de $300.

Inicia Cloud Shell

Si bien Google Cloud y Spanner se pueden operar de manera remota desde tu laptop, en este codelab usarás Google Cloud Shell, un entorno de línea de comandos que se ejecuta en la nube.

En Google Cloud Console, haz clic en el ícono de Cloud Shell en la barra de herramientas en la parte superior derecha:

El aprovisionamiento y la conexión al entorno deberían tomar solo unos minutos. Cuando termine el proceso, debería ver algo como lo siguiente:

Esta máquina virtual está cargada con todas las herramientas de desarrollo que necesitarás. Ofrece un directorio principal persistente de 5 GB y se ejecuta en Google Cloud, lo que permite mejorar considerablemente el rendimiento de la red y la autenticación. Todo tu trabajo en este codelab se puede hacer en un navegador. No es necesario que instales nada.

3. Tarea 1: Configura el entorno con Terraform

Crearemos una VPC personalizada con reglas de firewall y una subred. Abre la consola de Cloud y selecciona el proyecto que usarás.

1. Abre Cloud Shell, que se encuentra en la parte superior derecha de la consola, asegúrate de ver el ID del proyecto correcto en Cloud Shell y confirma cualquier mensaje para permitir el acceso.
2. Crea una carpeta llamada terraform-build y muévete a ella.

mkdir terraform-build  && cd terraform-build

3. Crea un archivo main.tf y un archivo variable.tf.

touch main.tf variable.tf 

4. Cambia a la vista del editor de Cloud Shell. Selecciona editor y asegúrate de permitir cualquier mensaje necesario para que se cargue la interfaz.
5. Una vez que se cargue, navega a File > Open Folder, ve a /home/your-user-name/terraform-build y selecciona Ok para abrir la carpeta en el editor.
6. Selecciona el archivo variable.tf y agrega lo siguiente. Reemplaza el texto your-project-id-here por el ID de tu proyecto real entre comillas.

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

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

7. A continuación, abre el archivo main.tf. Agregaremos código de Terraform para realizar varias acciones, como se explica a continuación.

Habilita las APIs	resource "google_project_service" "default"
Crea una VPC llamada python-net	resource "google_compute_network" "default"
Agrega una subred	resource "google_compute_subnetwork" "default"
Agrega dos reglas de firewall	resource "google_compute_firewall" "allow_icmp"resource "google_compute_firewall" "allow_ssh"

8. Copia y pega lo siguiente en el archivo 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. Vuelve a la terminal de Cloud Shell, asegúrate de estar en el directorio terraform-build cd terraform-build y ejecuta los siguientes comandos.

terraform init

Inicializa el directorio de trabajo. En este paso, se descargan los proveedores necesarios para la configuración determinada.

terraform plan

Genera un plan de ejecución que muestra las acciones que Terraform realizará para implementar tu infraestructura.

10. Ahora, para crear los recursos, ejecuta el comando terraform apply y escribe yes para ejecutarlo.

Verifica la configuración: Comprueba tu entorno para detectar lo siguiente:

• VPC llamada gemini-vpc-net
• subred
• firewall-rules

4. Tarea 2: Crea una puerta de enlace NAT y VMs con Terraform

Debemos otorgar acceso externo saliente a Internet, por lo que crearemos una puerta de enlace de Cloud NAT y la adjuntaremos.

1. Abre Cloud Shell, navega a la carpeta terraform-build y crea los siguientes archivos (tres en total). Los editaremos más adelante.

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

2. Cambia a la vista del editor de Cloud Shell, selecciona el archivo nat-vm.tf y agrega el siguiente código de Terraform. Esto creará una puerta de enlace NAT y dos VMs.

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. Cambia a la terminal de Cloud Shell, asegúrate de estar en la carpeta terraform-build y ejecuta terraform plan. Esto te mostrará que se agregarán 4 elementos. Luego, ejecuta terraform apply y escribe yes para crear la puerta de enlace de NAT y dos VMs.

Verifica la configuración: Comprueba tu entorno para detectar lo siguiente:

1 puerta de enlace NAT

1 Cloud Router

VM llamada cli-vm

VM llamada monitor-vm

5. Tarea 3: Configura VMs de la CLI y realiza pruebas

1. Navega a Instancias de VM. Selecciona la VM que comienza con cli-vm. Elige SSH.
2. Una vez que accedas a la VM a través de SSH, deberías tener acceso a ella. Creemos una carpeta para cuando ejecutemos la CLI de Gemini.

mkdir geminicli && cd geminicli

3. Para instalar la CLI de Gemini, necesitamos Node.js. Instala Node.js con el siguiente comando:

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

Ejecutar secuencia de comandos

sudo -E bash nodesource_setup.sh

Instala Node.js

sudo apt-get install -y nodejs

4. Establezcamos algunas variables que ayudarán a usar la opción de autenticación de Vertex AI para autenticar esto y realizar algunas pruebas más adelante. Nota: Reemplaza YOUR_PROJECT_ID por tu project ID real.

cat <<EOF >> ~/.bashrc 

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

Vuelve a cargar bash

source ~/.bashrc

5. Ahora, realicemos la autenticación. Ejecuta el siguiente comando en la VM y presiona y cuando se te solicite.

gcloud auth application-default login

6. A continuación, copia la URL que aparece y que comienza con https://. Abre una pestaña nueva en la ventana del navegador del lab y pega la URL. Acepta las instrucciones.
7. Cuando veas el siguiente mensaje, selecciona copiar, vuelve a la sesión de la VM cli-vm y, en Enter authorization code:, pega el código que copiaste y presiona Intro para autenticarte.

8. Ahora instalemos Gemini CLI. Para ello, ejecuta el comando

sudo npm install -g @google/gemini-cli

Una vez que completes el proceso, escribe gemini para iniciar la interfaz, selecciona el tema que prefieras y, en Select Auth method, elige Vertex AI.

9. Una vez que te autentiques, podrás comenzar a usar Gemini CLI.

Nota: Puedes modificar la pregunta de la instrucción por otra.

Supervisa la ruta del tráfico a Gemini a través de la VM de supervisión

1. Navega a Instancias de VM. Selecciona la VM que comienza con monitor-vm. Elige SSH.
2. Una vez que accedas a monitor-vm a través de SSH, deberías tener acceso
3. Usemos el comando dig para probar la ruta de conexión a la API de Gemini. Usaremos us-east1-aiplatform.googleapis.com

dig us-east1-aiplatform.googleapis.com

Deberías ver algo similar (la dirección será diferente). Ten en cuenta que la ruta se realiza a través de direcciones IP públicas, ya que la API es pública.

NO COPIAR

; <<>> 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. Ahora, hagamos una prueba rápida de ping para ver si podemos conectarnos a la API de Gemini. Este comando usará 4 pings para us-east1-aiplatform.googleapis.com, por lo que obtendremos una respuesta de la dirección pública de la API.

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

5. Volveremos a probar esta VM más adelante. Cierra la sesión de SSH y continuemos.

6. Tarea 4: Crea el extremo de PSC para googleapis con Terraform

Para habilitar la conectividad privada a nuestro extremo de la API de Vertex, crearemos un extremo de Private Service Connect para las APIs de Google. Esto nos permitirá usar una dirección IP privada que asignemos para enrutar el tráfico a las APIs de Google que necesitamos, en este caso, Vertex.

1. Abre Cloud Shell en la vista del editor si aún no está abierto. Crearemos lo siguiente:

• Crea una IP para el extremo de PSC 10.10.100.250 (resource "google_compute_global_address" "default")
• Crea un extremo de PSC para las APIs de Google (resource "google_compute_global_forwarding_rule" "default")

Abre el archivo psc.tf en la carpeta terraform-build. Agrega el siguiente código al archivo.

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. Cambia a la terminal de Cloud Shell y asegúrate de estar en la carpeta terraform-build. Luego, ejecuta terraform init y terraform plan. Verás que se agregarán 2 elementos.
   Luego, ejecuta terraform apply y escribe yes para crear el extremo de las APIs de Google de IP y PSC.
3. Verifica que exista el extremo

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

gcloud compute forwarding-rules describe pscgemini --global

7. Tarea 5. Crea una entrada de DNS manual para googleapis con Terraform

Puedes crear una entrada de DNS manual para que apunte al extremo de PSC con DNS privado. Esto afectaría a todas las redes que le asignes.

1. Navega a Servicios de red y selecciona Cloud DNS.
2. En las zonas, deberías ver una zona creada automáticamente para Private Service Connect para las APIs de Google, con el tipo de zona de directorio de servicios. Se puede usar para conectarse al extremo de PSC con el formato **SERVICE-ENDPOINT.p.googleapis.com. Ejemplo: aiplatform-pscgemini.p.googleapis.com
3. En este caso, queremos crear manualmente una entrada de DNS privada. La configuración será la siguiente:

• Crea una zona de DNS privada llamada "googleapis-private" para "googleapis.com" y restrínsela a la red "python-net".
• Agrega un registro A para asignar "googleapis.com" a la dirección IP "10.10.100.250".
• Agrega un registro CNAME para redireccionar todos los subdominios de "googleapis.com" (p.ej., www.googleapis.com) a "googleapis.com".

4. Abre Cloud Shell en la vista del editor si aún no está abierto. Abre el archivo dns.tf en la carpeta terraform-build. Agrega el siguiente código al archivo.

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. Cambia a la terminal de Cloud Shell y asegúrate de estar en la carpeta terraform-build. Luego, ejecuta terraform plan. Esto te mostrará qué elementos se agregarán.
   Luego, ejecuta terraform apply y escribe yes para crear la entrada de DNS privada.
6. Deberías ver una configuración con un registro A y un CNAME como este:

7. A continuación, verificamos la conectividad con estos cambios en monitor-vm.

8. Tarea 7: Verifica la conectividad del extremo a través de la dirección IP

Conectémonos a Gemini a través del extremo privado.

Nota: No es necesario realizar configuraciones manuales en la VM.

1. Ve a la instancia de VM monitor-vm. Selecciona SSH y establece una conexión SSH a la VM
2. Verifica la ruta de conectividad a us-east1-aiplatform.googleapis.com con el comando ping. Esto hará ping a la dirección IP en el DNS privado, un registro A para googleapis. Esta IP es un extremo de PSC y tus pings no se realizarán correctamente.

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

3. Verifica la ruta de conectividad con un ping usando la entrada DNS creada automáticamente para las APIs de Google de PSC con aiplatform-pscvertexgemini.p.googleapis.com. Esto apunta a la dirección IP del extremo de PSC, y tus pings no tendrán éxito.

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

4. Verifica la ruta de conectividad a us-east1-aiplatform.googleapis.com con el comando dig. Esta debe ser la dirección IP del extremo de PSC (10.10.100.250).

dig us-east1-aiplatform.googleapis.com

5. Una vez que se complete, puedes cerrar la sesión SSH de monitor-vm.
6. Ahora podemos ejecutar un volcado de TCP en cli-vm. Deberíamos abrir dos sesiones de SSH en la misma VM. Una sesión ejecutará el comando tcpdump y la otra usará la CLI de Gemini.
7. Establece una conexión SSH a la primera sesión en cli-vm.
8. Escribe el siguiente comando para ver la conectividad en un tcpdump

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

9. Ahora, establece una conexión SSH en la siguiente sesión de cli-vm.
10. Activa Gemini CLI escribiendo gemini.
11. Haz la siguiente pregunta: ¿De qué color es el cielo? para generar una llamada a la API de Gemini.

12. Presiona Intro para ejecutar y ver el resultado.
13. Regresa a la primera sesión en cli-vm. Deberías ver el resultado de tcpdump. Observarás que la dirección IP de la VM usa la dirección IP del extremo de PSC para conectarse a la API de Gemini.

Cierra todas las sesiones SSH en las instancias de VM

9. Limpieza

1. Ve a Cloud Shell, asegúrate de estar en el directorio terraform-build cd terraform-build y ejecuta el siguiente comando terraform destroy y escribe yes. Se quitarán todos los recursos que creaste en tu proyecto con Terraform.

10. Felicitaciones

¡Felicitaciones! Te conectaste correctamente a la CLI de Gemini con la dirección de la API pública y de forma privada con el extremo de Private Service Connect para las APIs de Google. Esta funcionalidad puede extender la conectividad de la API privada a tu entorno local o de otra nube que estén conectados a través de Interconnect, Cross-Cloud Interconnect y VPC.

Próximos pasos y más información

Puedes leer más sobre las redes de Vertex AI y consultar el repo de la CLI de Gemini.

Realiza tu próximo lab

Continúa tu Quest con Google Cloud y consulta estos otros labs de Google Cloud:

• Conceptos básicos de las redes en Google Cloud
• Explorador de IA generativa - Vertex AI
• Visita guiada por las redes de Cloud