Interface de ligne de commande Gemini sur GCE avec un point de terminaison Private Service Connect

1. Présentation

Vous pouvez utiliser la CLI Gemini dans vos environnements locaux et virtuels. Gemini CLI est un agent IA Open Source qui apporte la puissance de Gemini directement dans votre terminal. D'un point de vue réseau, lorsque vous utilisez la Gemini CLI, elle appelle l'API Gemini via l'adresse IP de l'API, qui est accessible publiquement.

Que se passe-t-il si vous souhaitez utiliser la CLI Gemini sur une machine Google Compute Engine, mais que vous voulez vous connecter à l'API de manière privée ? Dans cet atelier de programmation, vous allez découvrir comment configurer un point de terminaison Private Service Connect pour les API Google, afin de router le trafic vers une adresse IP interne que vous spécifiez.

Les configurations seront une combinaison de Terraform, gcloud et de la console.

Dans cet atelier, vous allez apprendre à effectuer la tâche suivante :

• Configurer une instance de VM et Cloud NAT
• Installer la CLI Gemini et s'authentifier
• Configurer un point de terminaison Private Service Connect pour se connecter à Googleapis
• Vérifier le chemin de connectivité vers *.googleais
• Configurer des entrées DNS manuelles

Dans cet atelier, vous allez créer le modèle suivant.

Figure 1.

2. Configurer les services Google Cloud

Configuration de l'environnement au rythme de chacun

1. Connectez-vous à la console Google Cloud, puis créez un projet ou réutilisez un projet existant. Si vous n'avez pas encore de compte Gmail ou Google Workspace, vous devez en créer un.

• Le nom du projet est le nom à afficher pour les participants au projet. Il s'agit d'une chaîne de caractères non utilisée par les API Google. Vous pourrez toujours le modifier.
• L'ID du projet est unique parmi tous les projets Google Cloud et non modifiable une fois défini. La console Cloud génère automatiquement une chaîne unique (en général, vous n'y accordez d'importance particulière). Dans la plupart des ateliers de programmation, vous devrez indiquer l'ID de votre projet (généralement identifié par PROJECT_ID). Si l'ID généré ne vous convient pas, vous pouvez en générer un autre de manière aléatoire. Vous pouvez également en spécifier un et voir s'il est disponible. Après cette étape, l'ID n'est plus modifiable et restera donc le même pour toute la durée du projet.
• Pour information, il existe une troisième valeur (le numéro de projet) que certaines API utilisent. Pour en savoir plus sur ces trois valeurs, consultez la documentation.

Attention : Un ID de projet est unique. Une fois que vous l'avez choisi, personne d'autre ne peut l'employer. Vous en êtes le seul utilisateur. Même si un projet est supprimé, son ID ne peut pas être réutilisé.

Remarque : Si vous utilisez un compte Gmail, vous pouvez conserver l'emplacement par défaut défini sur Aucune organisation. Si vous utilisez un compte Google Workspace, choisissez un emplacement qui ait du sens pour votre organisation.

2. Vous devez ensuite activer la facturation dans la console Cloud pour utiliser les ressources/API Cloud. L'exécution de cet atelier de programmation est très peu coûteuse, voire sans frais. Pour désactiver les ressources et éviter ainsi que des frais ne vous soient facturés après ce tutoriel, vous pouvez supprimer le projet ou les ressources que vous avez créées. Les nouveaux utilisateurs de Google Cloud peuvent participer au programme d'essai sans frais pour bénéficier d'un crédit de 300 $.

Démarrer Cloud Shell

Bien que Google Cloud puisse être utilisé à distance depuis votre ordinateur portable, nous allons nous servir de Google Cloud Shell pour cet atelier de programmation, un environnement de ligne de commande exécuté dans le cloud.

Dans la console Google Cloud, cliquez sur l'icône Cloud Shell dans la barre d'outils supérieure :

Le provisionnement et la connexion à l'environnement prennent quelques instants seulement. Une fois l'opération terminée, le résultat devrait ressembler à ceci :

Cette machine virtuelle contient tous les outils de développement nécessaires. Elle comprend un répertoire d'accueil persistant de 5 Go et s'exécute sur Google Cloud, ce qui améliore nettement les performances du réseau et l'authentification. Vous pouvez effectuer toutes les tâches de cet atelier de programmation dans un navigateur. Vous n'avez rien à installer.

3. Tâche 1 : Configurer l'environnement avec Terraform

Nous allons créer un VPC personnalisé avec des règles de pare-feu et un sous-réseau. Ouvrez la console Cloud et sélectionnez le projet que vous allez utiliser.

1. Ouvrez Cloud Shell en haut à droite de la console. Assurez-vous que l'ID de projet correct s'affiche dans Cloud Shell et confirmez les éventuelles invites d'autorisation d'accès.
2. Créez un dossier appelé "terraform-build" et accédez-y.

mkdir terraform-build  && cd terraform-build

3. Créez un fichier main.tf et variable.tf.

touch main.tf variable.tf 

4. Passez à la vue Éditeur Cloud Shell. Sélectionnez Éditeur et assurez-vous d'autoriser toutes les invites nécessaires pour que l'interface puisse se charger.
5. Une fois le fichier chargé, accédez à File > Open Folder (Fichier > Ouvrir le dossier), puis accédez à /home/your-user-name/terraform-build et sélectionnez OK pour ouvrir le dossier dans l'éditeur.
6. Sélectionnez le fichier variable.tf et ajoutez-y les éléments suivants. Remplacez le texte your-project-id-here par l'ID de votre projet entre guillemets.

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

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

7. Ouvrez ensuite le fichier main.tf. Nous allons ajouter du code Terraform pour effectuer différentes actions, comme expliqué ci-dessous.

Activer les API	resource "google_project_service" "default"
Créer un VPC appelé python-net	resource "google_compute_network" "default"
Ajouter un sous-réseau	resource "google_compute_subnetwork" "default"
Ajouter deux règles de pare-feu	resource "google_compute_firewall" "allow_icmp"resource "google_compute_firewall" "allow_ssh"

8. Copiez et collez le texte suivant dans le fichier 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. Revenez au terminal Cloud Shell, assurez-vous d'être dans le répertoire terraform-build cd terraform-build, puis exécutez les commandes suivantes :

terraform init

Initialise le répertoire de travail. Cette étape télécharge les fournisseurs requis pour la configuration donnée.

terraform plan

Génère un plan d'exécution, qui indique les actions que Terraform effectuera pour déployer votre infrastructure.

10. Pour créer les ressources, exécutez la commande terraform apply et saisissez yes pour l'exécuter.

Vérifiez votre configuration : vérifiez que votre environnement contient

• VPC appelé gemini-vpc-net
• sous-réseau
• firewall-rules

4. Tâche 2 : Créer une passerelle NAT et des VM avec Terraform

Nous devons accorder un accès externe sortant à Internet. Créons donc une passerelle Cloud NAT et associons-la.

1. Ouvrez Cloud Shell, accédez au dossier terraform-build et créez les fichiers suivants (trois fichiers au total). Nous les modifierons plus tard.

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

2. Passez à la vue Éditeur Cloud Shell, sélectionnez le fichier nat-vm.tf, puis ajoutez le code Terraform suivant. Cela créera une passerelle NAT et deux 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. Passez au terminal Cloud Shell, assurez-vous d'être dans le dossier terraform-build, puis exécutez terraform plan. Vous verrez que quatre éléments seront ajoutés. Ensuite, exécutez terraform apply et saisissez yes pour créer la passerelle NAT et les deux VM.

Vérifiez votre configuration : vérifiez que votre environnement contient

1 passerelle NAT

1 routeur cloud

VM nommée cli-vm

VM nommée monitor-vm

5. Tâche 3 : Configurer et tester les VM de la CLI

1. Accédez à "Instances de VM". Sélectionnez la VM commençant par cli-vm. Sélectionnez SSH.
2. Une fois que vous avez établi une connexion SSH, vous devriez avoir accès à la VM. Créons un dossier pour l'exécution de Gemini CLI.

mkdir geminicli && cd geminicli

3. Pour installer la CLI Gemini, nous avons besoin de Node.js. Installez Node.js à l'aide de la commande suivante :

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

Exécuter le script

sudo -E bash nodesource_setup.sh

Installer Node.js

sudo apt-get install -y nodejs

4. Définissons quelques variables qui nous aideront à utiliser l'option d'authentification Vertex AI pour effectuer des tests ultérieurement. PS : Remplacez YOUR_PROJECT_ID par votre project ID.

cat <<EOF >> ~/.bashrc 

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

Actualiser bash

source ~/.bashrc

5. Authentifions-nous maintenant. Exécutez la commande suivante dans la VM, puis appuyez sur y lorsque vous y êtes invité.

gcloud auth application-default login

6. Copiez ensuite l'URL qui commence par https://, ouvrez un nouvel onglet dans la fenêtre du navigateur de l'atelier et collez l'URL. Acceptez les requêtes.
7. Lorsque le message suivant s'affiche, sélectionnez "Copier", revenez à la session cli-vm de la VM, puis collez le code copié dans Enter authorization code: et appuyez sur Entrée pour vous authentifier.

8. Installons maintenant Gemini CLI en exécutant la commande

sudo npm install -g @google/gemini-cli

Une fois l'opération terminée, saisissez gemini pour lancer l'interface, sélectionnez le thème de votre choix, puis, sous Select Auth method (Sélectionner la méthode d'authentification), choisissez Vertex AI.

9. Une fois authentifié, vous pouvez commencer à utiliser Gemini CLI.

Remarque : Vous pouvez modifier la question de la requête.

Surveiller le trafic vers Gemini via la VM de surveillance

1. Accédez à "Instances de VM". Sélectionnez la VM commençant par monitor-vm. Sélectionnez SSH.
2. Une fois que vous vous êtes connecté en SSH à monitor-vm, vous devriez avoir accès
3. Utilisons la commande dig pour tester le chemin de connexion à l'API Gemini. Nous allons utiliser le

dig us-east1-aiplatform.googleapis.com

Le résultat doit ressembler à ceci (l'adresse sera différente). Notez que le chemin d'accès se fait via des adresses IP publiques, car l'API est une API publique.

NE COPIEZ PAS

; <<>> 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. Effectuons maintenant un test ping rapide pour voir si nous pouvons nous connecter à l'API Gemini. Cette commande utilisera quatre pings à l'adresse us-east1-aiplatform.googleapis.com pour obtenir une réponse de l'adresse publique de l'API.

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

5. Nous reviendrons tester cette VM plus tard. Fermez la session SSH et poursuivons.

6. Tâche 4 : Créer le point de terminaison PSC vers googleapis avec Terraform

Pour activer la connectivité privée à notre point de terminaison de l'API Vertex, nous allons créer un point de terminaison Private Service Connect pour les API Google. Cela nous permettra d'utiliser une adresse IP privée que nous attribuons pour acheminer le trafic vers les API Google dont nous avons besoin, en l'occurrence Vertex.

1. Ouvrez Cloud Shell en mode Éditeur si ce n'est pas déjà fait. Nous allons créer les éléments suivants :

• Créez une adresse IP pour le point de terminaison PSC 10.10.100.250 (resource "google_compute_global_address" "default")
• Créer un point de terminaison PSC pour les API Google (resource "google_compute_global_forwarding_rule" "default")

Ouvrez le fichier psc.tf dans le dossier terraform-build. Ajoutez le code suivant au fichier.

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. Passez au terminal Cloud Shell et assurez-vous d'être dans le dossier terraform-build. Exécutez ensuite terraform init. Vous verrez que deux éléments seront ajoutés.
   Exécutez ensuite terraform apply et saisissez yes pour créer le point de terminaison des API Google IP et PSC.terraform plan
3. Vérifier l'existence du point de terminaison

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

gcloud compute forwarding-rules describe pscgemini --global

7. Tâche 5 : Créer une entrée DNS manuelle vers googleapis avec Terraform

Vous pouvez créer une entrée DNS manuelle pour pointer vers le point de terminaison PSC à l'aide du DNS privé. Cela affecterait tous les réseaux que vous lui attribuez.

1. Accédez à "Services réseau", puis sélectionnez "Cloud DNS".
2. Dans les zones, vous devriez voir une zone créée automatiquement pour Private Service Connect pour les API Google, avec le type de zone "Annuaire de services". Vous pouvez l'utiliser pour vous connecter au point de terminaison PSC au format **SERVICE-ENDPOINT.p.googleapis.com. Exemple : aiplatform-pscgemini.p.googleapis.com
3. Dans ce cas, nous souhaitons créer manuellement une entrée DNS privée. La configuration sera la suivante :

• Créez une zone DNS privée nommée "googleapis-private" pour "googleapis.com" et limitez-la au réseau "python-net".
• Ajoutez un enregistrement A pour mapper "googleapis.com" à l'adresse IP "10.10.100.250".
• Ajoutez un enregistrement CNAME pour rediriger tous les sous-domaines de "googleapis.com" (par exemple, www.googleapis.com) vers "googleapis.com".

4. Ouvrez Cloud Shell en mode Éditeur si ce n'est pas déjà fait. Ouvrez le fichier dns.tf dans le dossier terraform-build. Ajoutez le code suivant au fichier.

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. Passez au terminal Cloud Shell et assurez-vous d'être dans le dossier terraform-build. Exécutez ensuite terraform plan pour afficher les éléments qui seront ajoutés,
   puis exécutez terraform apply et saisissez yes pour créer l'entrée DNS privée.
6. Vous devriez voir une configuration avec un enregistrement A et un CNAME comme celui-ci :

7. Nous allons ensuite vérifier la connectivité avec ces modifications sur monitor-vm.

8. Tâche 7 : Vérifier la connectivité du point de terminaison via l'adresse IP

Connectons-nous à Gemini à l'aide du point de terminaison privé.

Remarque : Aucune configuration manuelle n'est nécessaire sur la VM.

1. Accédez à l'instance de VM monitor-vm. Sélectionnez SSH, puis connectez-vous en SSH à la VM.
2. Vérifiez le chemin de connectivité vers us-east1-aiplatform.googleapis.com à l'aide de la commande ping. Cela ping l'adresse IP dans le DNS privé, enregistrement A pour googleapis. Cette adresse IP est un point de terminaison PSC et vos pings échoueront.

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

3. Vérifiez le chemin de connectivité avec ping à l'aide de l'entrée DNS créée automatiquement pour les API Google PSC avec aiplatform-pscvertexgemini.p.googleapis.com. Cela pointe vers l'adresse IP du point de terminaison PSC et vos pings échoueront.

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

4. Vérifiez le chemin de connectivité vers us-east1-aiplatform.googleapis.com à l'aide de la commande dig. Il doit s'agir de l'adresse IP du point de terminaison PSC (10.10.100.250).

dig us-east1-aiplatform.googleapis.com

5. Une fois l'opération terminée, vous pouvez fermer la session SSH monitor-vm.
6. Nous pouvons maintenant exécuter un vidage TCP sur cli-vm. Nous devons ouvrir deux sessions SSH sur la même VM. Une session exécutera la commande tcpdump, tandis que l'autre utilisera Gemini CLI.
7. Connectez-vous en SSH à la première session sur cli-vm.
8. Saisissez la commande suivante pour afficher la connectivité dans un tcpdump.

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

9. Connectez-vous en SSH à la session suivante sur cli-vm.
10. Activez Gemini CLI en saisissant gemini.
11. Posez la question "De quelle couleur est le ciel ?" pour générer un appel à l'API Gemini.

12. Appuyez sur Entrée pour exécuter la requête et afficher le résultat.
13. Rebasculez vers la première session sur cli-vm. Le résultat de tcpdump devrait s'afficher. Vous remarquerez que l'adresse IP de la VM utilise l'adresse IP du point de terminaison PSC pour se connecter à l'API Gemini.

Fermer toutes les sessions SSH aux instances de VM

9. Effectuer un nettoyage

1. Accédez à Cloud Shell, assurez-vous d'être dans le répertoire terraform-build cd terraform-build, puis exécutez la commande suivante terraform destroy et saisissez yes. Toutes les ressources que vous avez créées dans votre projet avec Terraform seront supprimées.

10. Félicitations

Félicitations ! Vous vous êtes connecté à l'interface de ligne de commande Gemini à l'aide de l'adresse de l'API publique et de manière privée à l'aide du point de terminaison Private Service Connect pour les API Google. Cette fonctionnalité peut étendre la connectivité des API privées à votre environnement sur site/autre cloud connecté via (Interconnect, Cross-Cloud Interconnect et VPC).

Étapes suivantes et informations supplémentaires

Pour en savoir plus sur la mise en réseau Vertex AI, consultez le dépôt de l'interface de ligne de commande Gemini.

Atelier suivant

Continuez sur votre lancée avec Google Cloud et découvrez ces autres ateliers Google Cloud :

• Principes de base de la mise en réseau dans Google Cloud
• Explorateur de l'IA générative – Vertex AI
• Visite guidée de la mise en réseau cloud