Intent to Infrastructure : migration vers GKE pilotée par un agent

1. Introduction

Dans cet atelier de programmation, vous allez découvrir comment utiliser un agent IA pour effectuer automatiquement une migration d'infrastructure complexe. Au lieu d'écrire manuellement des fichiers manifestes Kubernetes ou d'exécuter des scripts d'automatisation, vous exprimerez votre intention en langage naturel. L'agent utilisera le protocole de contexte de modèle (MCP) et le serveur Gemini Cloud Assist pour générer et appliquer la configuration à votre place.

Important : Cet atelier de programmation met en avant le serveur MCP Gemini Cloud Assist (GCA), qui est actuellement en version Preview privée. Vous pouvez continuer l'atelier de programmation même si vous n'avez pas accès à l'ensemble des fonctionnalités. Toutefois, si vous n'avez pas accès aux fonctionnalités de mutation (en particulier à l'outil invoke_operation), l'agent ne pourra pas appliquer automatiquement les modifications. Dans ce cas, vous devrez appliquer manuellement les fichiers manifestes Kubernetes générés. Pour en savoir plus, contactez l'équipe chargée de votre compte.

Fonctionnalités du serveur MCP GCA

Le serveur MCP GCA fournit plusieurs outils spécialisés à l'agent :

• ask_cloud_assist: il s'agit de l'interface principale pour l'assistance Google Cloud Platform et pour l'agent Gemini Cloud Assist. Toutes les fonctionnalités de Gemini Cloud Assist sont accessibles via cet outil, qui englobe les fonctionnalités des autres outils MCP.
• design_infra: il prend en charge les workflows de conception et d'architecture d'infrastructure sur Google Cloud Platform.
• investigate_issue: il prend en charge les workflows de dépannage dans Google Cloud. Il peut effectuer un dépannage rapide ou plus approfondi via une ressource d'investigation.
• invoke_operation: il prend en charge les workflows de création, de mise à jour et de suppression de ressources dans Google Cloud. Cet outil n'est fonctionnel que lorsque les actions de l'agent sont activées. Les opérations d'écriture dans Gemini Cloud Assist ne peuvent être exécutées que par l'invocation de cet outil.
• optimize_costs: il prend en charge les workflows d'analyse, de suivi et d'optimisation des coûts Google Cloud. Il fournit une répartition détaillée des dépenses et identifie les possibilités de réduction des coûts en détectant les ressources inactives ou sous-utilisées.

Vous commencerez par un environnement préconfiguré avec un cluster GKE et un modèle téléchargé. Vous utiliserez ensuite gemini-cli pour inviter l'agent à migrer une charge de travail de Cloud Run vers GKE et à démarrer une instance d'inférence Gemma avec vLLM à l'aide du modèle préconfiguré dans votre bucket de stockage.

Objectifs de l'atelier

• Préconfigurer un cluster GKE et télécharger un modèle Gemma à l'aide de Terraform.
• Configurer gemini-cli avec des règles d'agent et un serveur MCP.
• Utiliser un prompt spécifique en langage naturel pour demander à l'agent d'effectuer la migration et le déploiement complets.
• Vérifier le déploiement effectué par l'agent.

Ce dont vous avez besoin

• Un navigateur Web tel que Chrome.
• Un projet Google Cloud avec facturation activée.
• Un jeton Hugging Face (requis pour télécharger le modèle Gemma lors de la phase de préconfiguration).

Cet atelier de programmation s'adresse aux développeurs de tous niveaux, y compris aux débutants.

Durée estimée : 45 à 60 minutes.

2. Avant de commencer

Créer ou sélectionner un projet Google Cloud

1. Dans Google Cloud Console, sélectionnez ou créez un projet Google Cloud.
2. Assurez-vous que la facturation est activée pour votre projet Cloud.

Démarrer Cloud Shell

1. Cliquez sur Activer Cloud Shell en haut de la console Google Cloud.
2. Vérifiez l'authentification :

gcloud auth list

3. Confirmez votre projet :

gcloud config get project

4. Définissez-le si nécessaire :

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Activer les API

Exécutez cette commande pour activer toutes les API requises :

gcloud services enable \
  run.googleapis.com \
  container.googleapis.com \
  aiplatform.googleapis.com \
  compute.googleapis.com \
  cloudbuild.googleapis.com \
  cloudresourcemanager.googleapis.com

Activez également le service MCP Gemini Cloud Assist :

gcloud beta services mcp enable geminicloudassist.googleapis.com

3. Préconfigurer l'environnement

Dans cette étape, vous allez préparer l'environnement en créant une image de chatbot personnalisée, en créant le cluster GKE et en téléchargeant le modèle Gemma dans un bucket Cloud Storage.

Souvent, les entreprises commencent par l'API Gemini, mais décident ensuite de migrer vers un modèle auto-hébergé pour un meilleur contrôle, une personnalisation accrue ou pour utiliser une version affinée spécifique à leur activité. Dans cet atelier de programmation, nous utilisons Gemma comme exemple de modèle ouvert puissant que vous pouvez héberger vous-même sur GKE. En le préconfigurant dans un bucket Cloud Storage, nous le rendons disponible pour notre cluster.

Télécharger les composants de démonstration

Clonez le dossier spécifique à partir du dépôt GitHub.

git clone --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/next-26-keynotes.git
cd next-26-keynotes
git sparse-checkout set devkey/intent-to-infrastructure
cd devkey/intent-to-infrastructure

Créer une image de chatbot

Avant de provisionner l'infrastructure, vous devez créer l'image de chatbot personnalisée et la transférer vers Artifact Registry. Cette image sera utilisée par Cloud Run à l'étape suivante.

1. Créez un dépôt Artifact Registry nommé chatbot-repo dans asia-southeast1 :

   gcloud artifacts repositories create chatbot-repo \
       --repository-format=docker \
       --location=asia-southeast1 \
       --description="Chatbot Docker repository"
   

2. Accédez au répertoire src :

   cd src
   

3. Créez et transférez l'image à l'aide de Cloud Build :

   gcloud builds submit --config cloudbuild.yaml \
       --substitutions=_LOCATION="asia-southeast1",_REPOSITORY_ID="chatbot-repo",_IMAGE_NAME="chatbot",_IMAGE_TAG="latest"
   

4. Revenez au répertoire racine du projet :

   cd ..
   

Provisionner l'infrastructure de base

Accédez au répertoire terraform et exécutez l'étape 1 pour créer le cluster GKE.

cd terraform
./deploy.sh demo step1 apply

Remarque : Si vous recevez une erreur "Autorisation refusée" lors de l'exécution de deploy.sh, vous devrez peut-être le rendre exécutable en exécutant chmod +x deploy.sh.

Ce script utilise Terraform pour provisionner l'infrastructure de base. Il crée le VPC, le cluster GKE et les comptes de service, puis déploie le service Cloud Run initial à l'aide de l'image de chatbot que vous venez de créer.

Au cours du processus, Terraform affiche le plan et vous demande de confirmer. Vous devrez saisir yes pour approuver et continuer :

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

L'ensemble du processus peut prendre entre 15 et 20 minutes.

Une fois le déploiement terminé, recherchez cloud_run_url dans les sorties Terraform imprimées dans le terminal. Cliquez sur l'URL pour ouvrir le chatbot dans votre navigateur. Vous pouvez désormais interagir avec le chatbot, qui s'exécute actuellement sur Gemini 2.5 Flash.

Télécharger le modèle

Dans cette étape, nous allons préconfigurer le modèle Gemma dans un bucket Cloud Storage. Bien que nous commencions par l'API Gemini gérée, vous pouvez choisir d'exécuter un modèle personnalisé affiné ou un autre modèle ouvert personnalisé. Vous pouvez également simplement conserver l'exécution du modèle gérée dans votre propre cluster pour des raisons de sécurité ou de conformité. La préconfiguration du modèle nous permet de migrer de l'API Gemini gérée vers un modèle auto-hébergé sur GKE.

Exécutez l'étape 2 pour télécharger le modèle Gemma dans votre bucket GCS. Vous aurez besoin de votre jeton Hugging Face. Ce processus s'exécute sur votre cluster GKE et prendra environ 15 minutes (ou plus en fonction du trafic) pour télécharger le modèle à partir de Hugging Face et le transférer vers votre bucket pour une utilisation ultérieure.

./deploy.sh demo step2 apply -var="hf_token=<YOUR_HF_TOKEN>"

Cette commande Terraform crée un job Kubernetes sur votre cluster GKE pour gérer le téléchargement. Le script Terraform restera actif tant que le job est en cours d'exécution.

Si vous souhaitez suivre la progression à partir d'une autre session shell ou vérifier qu'elle est terminée après l'exécution, vous pouvez exécuter la commande suivante :

kubectl get jobs

4. Configurer l'agent et le MCP

Nous allons maintenant configurer l'agent qui effectuera la migration. Nous allons utiliser gemini-cli et l'équiper de règles pour interagir avec l'environnement.

Le serveur MCP Gemini Cloud Assist (GCA) est un composant essentiel de ce flux. Il sert de pont entre votre agent côté client et Google Cloud, ce qui lui permet d'effectuer des investigations, de générer des plans (comme les commandes gcloud et kubectl) et d'appliquer directement des modifications aux ressources de votre projet cloud.

Assurez-vous de disposer d'un rôle qui vous permet d'appeler des outils MCP, tels que roles/geminicloudassist.user. Si vous rencontrez des problèmes d'autorisation ultérieurement, consultez la documentation sur la configuration des rôles IAM pour Cloud Assist.

Pour obtenir des instructions plus détaillées sur l'intégration de Gemini Cloud Assist à des outils tiers, consultez la documentation Intégrer Gemini Cloud Assist à des outils tiers à l'aide de MCP.

Installer l'extension Gemini Cloud Assist

1. Authentifiez-vous à l'aide des identifiants par défaut de l'application (ADC) en exécutant la commande suivante :

gcloud auth application-default login

2. Installez le serveur MCP en tant qu'extension Gemini CLI :

gemini extensions install https://github.com/GoogleCloudPlatform/gemini-cloud-assist-mcp

Remarque : Cette commande installe à la fois le serveur MCP et une compétence spécialisée. Cette compétence aide Gemini CLI à comprendre les contextes appropriés dans lesquels utiliser les outils Cloud Assist.

3. Vérifiez que la compétence a bien été installée : démarrez gemini et exécutez la commande suivante pour afficher la liste des compétences actives :

/skills list

Vérifiez que la compétence associée à Gemini Cloud Assist s'affiche dans la liste. Saisissez exit pour revenir à votre invite Cloud Shell.

Activer les mutations dans Gemini Cloud Assist

Pour autoriser l'agent à appliquer des modifications à votre infrastructure, vous devez activer les fonctionnalités de mutation dans l'interface utilisateur de Gemini Cloud Assist.

1. Ouvrez la barre latérale Gemini Assist en cliquant sur le logo Gemini en haut à droite de la fenêtre Google Cloud Console.
   
   
2. Activez toutes les API nécessaires listées dans la barre latérale.
   
   
3. Accédez aux paramètres dans la barre latérale et cochez la case "Activer Cloud Assist pour exécuter des actions".
   
   
   

Configurer les règles de l'agent

Le répertoire du projet inclut un fichier gemini.md personnalisé à la racine du dossier (intent-to-infrastructure). Ce fichier contient des règles qui guident l'agent pour qu'il utilise les outils appropriés.

Vérifiez que ce fichier existe dans votre répertoire. Vous devez exécuter gemini à partir de ce répertoire afin qu'il ait accès aux fichiers Terraform, au code de l'application et au fichier de règles gemini.md.

5. Étape 1 : Migrer le chatbot vers GKE

Nous allons maintenant utiliser l'agent pour effectuer la première partie de la migration : déplacer l'application de chatbot de Cloud Run vers GKE.

1. Démarrez gemini à partir de la racine du répertoire intent-to-infrastructure (en vous assurant qu'il a accès à gemini.md).
2. Tout d'abord, demandons à l'agent d'explorer le projet pour comprendre l'application et l'infrastructure. Saisissez le prompt suivant :

Tell me about the app and infrastructure in this project

L'agent doit lire les fichiers du répertoire et vous donner un aperçu de l'application de chatbot et de la configuration Terraform.

3. Utilisez maintenant le prompt suivant pour demander à l'agent d'effectuer la migration.

Convert my Cloud Run service to the equivalent on GKE.

4. L'agent doit procéder comme suit :
   • Utiliser l'outil ask_cloud_assist pour comprendre le contexte.
   • Utiliser l'outil design_infra pour générer le fichier YAML Kubernetes pour l'application de chatbot.
   • Demander : "Voulez-vous appliquer cette configuration ?"

Remarque : Lorsque gemini tente d'utiliser un outil pour la première fois, il vous demande l'autorisation d'accéder aux outils fournis par le serveur MCP. Vous devez sélectionner Autoriser pour permettre à l'agent de continuer.

5. Répondez par yes pour appliquer les modifications. L'agent utilisera invoke_operation pour déployer les ressources sur votre cluster GKE.

Vérifier l'étape 1

1. Obtenez la liste des services :

kubectl get services

Un service pour l'application de chatbot doit s'exécuter.

2. Transférez le port du service pour accéder au chatbot :

kubectl port-forward svc/chatbot-service 8080:80

(Remarque : Remplacez

chatbot-service

par le nom réel du service généré par l'agent s'il est différent).

Testez le chatbot. Il doit toujours répondre à l'aide de l'API Gemini (comme il a été configuré dans Cloud Run).

6. Étape 2 : Déployer Gemma via vLLM et se reconnecter

Dans cette étape, nous allons utiliser l'agent pour déployer un modèle Gemma auto-hébergé sur GKE et y reconnecter notre application.

1. Dans la même session gemini, saisissez le prompt suivant :

Now that the chatbot is on GKE, add a vLLM service running the Gemma model from my storage bucket in the same cluster. Make sure to give the vLLM service at least 10 minutes to start up to account for loading the large model. Then, update the chatbot service to reference this vLLM service instead of the Gemini API.

2. L'agent doit procéder comme suit :
   • Utiliser design_infra pour générer le fichier YAML pour le déploiement et le service vLLM.
   • Mettre à jour le fichier YAML de déploiement du chatbot pour modifier les variables d'environnement (ou la configuration) afin qu'elles pointent vers le nouveau service vLLM au lieu de l'API Gemini.
   • Demander une confirmation pour appliquer les modifications.
3. Répondez par yes pour appliquer les modifications.

Vérifier l'étape 2

1. Obtenez à nouveau la liste des pods :

kubectl get pods

Vous devriez maintenant voir des pods pour le chatbot et vLLM.

Remarque : Même lorsque le pod vLLM est à l'état Running, le serveur peut mettre jusqu'à 10 minutes pour charger complètement les pondérations du modèle à partir du bucket de stockage et commencer à diffuser en raison de la taille importante du modèle. Vous pouvez suivre la progression du chargement en consultant les journaux :

kubectl logs -f deployment/gemma-vllm -c vllm-server

2. Une fois vLLM prêt, transférez à nouveau le port du service de chatbot si nécessaire et testez-le. Il devrait maintenant être alimenté par votre modèle Gemma auto-hébergé.

7. Effectuer un nettoyage

Pour éviter que votre compte Google Cloud ne soit facturé en permanence, supprimez les ressources créées lors de cet atelier de programmation.

Exécutez la commande de destruction pour l'infrastructure de base :

cd terraform
./deploy.sh demo step1 destroy

Vous pouvez également désinstaller ou désactiver l'extension Gemini Cloud Assist si vous souhaitez nettoyer votre environnement local. Utilisez gemini extensions uninstall ou gemini extensions disable, suivi du nom de l'extension.

8. Étape suivante

Pour en savoir plus sur Gemini Cloud Assist et ses fonctionnalités avancées, consultez les ressources suivantes :

• Résoudre des problèmes à l'aide de Cloud Assist Investigations
• Configurer le mode proactif

9. Félicitations

Félicitations Vous avez réussi à effectuer une migration d'une charge de travail vers GKE à l'aide d'un agent, en utilisant le langage naturel et le MCP.