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

1. Introduction

Dans cet atelier de programmation, vous allez apprendre à utiliser un agent d'IA pour effectuer automatiquement une migration d'infrastructure complexe. Au lieu d'écrire manuellement des manifestes Kubernetes ou d'exécuter des scripts d'automatisation, vous exprimerez votre intention en langage naturel. L'agent utilisera le protocole MCP (Model Context Protocol) 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 quand même suivre l'atelier de programmation même si vous n'avez pas accès à l'ensemble complet 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 les modifications automatiquement. 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 celles des autres outils MCP.
• design_infra : prend en charge les workflows de conception et d'architecture d'infrastructure sur Google Cloud Platform.
• investigate_issue : compatible avec les workflows de dépannage dans Google Cloud. Il peut effectuer un dépannage rapide ou plus approfondi à l'aide d'une ressource d'investigation.
• invoke_operation : prend en charge les workflows de création, de mise à jour et de suppression de ressources dans Google Cloud. Cet outil ne fonctionne 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 : permet d'analyser, de suivre et d'optimiser les coûts Google Cloud. Il fournit des détails sur les dépenses et identifie les opportunités de réduction des coûts en détectant les ressources inactives ou sous-utilisées.

Vous commencerez avec un environnement préconfiguré comprenant 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 intermédiaire dans votre bucket de stockage.

Objectifs de l'atelier

• Mettez en scène un cluster GKE et téléchargez un modèle Gemma à l'aide de Terraform.
• Configurez gemini-cli avec des règles d'agent et un serveur MCP.
• Utilisez un prompt en langage naturel spécifique pour demander à l'agent d'effectuer la migration et le déploiement complets.
• Vérifiez le déploiement effectué par l'agent.

Prérequis

• 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 pendant la phase de préparation).

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 la console Google Cloud, 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-la si nécessaire :

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

Activer les API

Exécutez la commande suivante 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éparer 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 organisations commencent par utiliser l'API Gemini, mais décident ensuite de migrer vers un modèle auto-hébergé pour bénéficier d'un contrôle et d'une personnalisation plus poussés, 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éparant dans un bucket Cloud Storage, vous le mettez à la disposition de votre 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 du chatbot personnalisé 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 à la 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" lorsque vous exécutez 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 affichera le plan et vous demandera de le 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 affichées dans le terminal. Cliquez sur l'URL pour ouvrir le chatbot dans votre navigateur. Vous pouvez désormais interagir avec le chatbot, qui fonctionne actuellement avec Gemini 2.5 Flash.

Télécharger le modèle

Dans cette étape, nous allons préparer 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 souhaiter 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éparation du modèle ici 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, selon le trafic) pour télécharger le modèle depuis Hugging Face et l'importer dans 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 sera en cours d'exécution.

Si vous souhaitez surveiller la progression à partir d'une autre session de 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 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 des modifications directement aux ressources de votre projet cloud.

Assurez-vous de disposer d'un rôle qui vous permet d'appeler les outils MCP, comme roles/geminicloudassist.user. Si vous rencontrez des problèmes d'autorisation par la suite, 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 lister les compétences actives :

/skills list

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

Activer les mutations dans Gemini Cloud Assist

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

1. Ouvrez la barre latérale Gemini Assist en cliquant sur le logo Gemini en haut à droite de la fenêtre de la console Google Cloud.
   
   
2. Activez les API nécessaires listées dans la barre latérale.
   
   
3. Accédez aux paramètres dans la barre latérale, puis cochez Autoriser Cloud Assist à 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 bons outils.

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. Commençons par demander à 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. Maintenant, utilisez la requête suivante pour demander à l'agent d'effectuer la migration.

Convert my Cloud Run service to the equivalent on GKE.

4. L'agent doit :
   • Utilisez l'outil ask_cloud_assist pour comprendre le contexte.
   • Utilisez l'outil design_infra pour générer le fichier YAML Kubernetes pour l'application de chatbot.
   • Demandez : "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 avec yes pour appliquer les modifications. L'agent utilisera invoke_operation pour déployer les ressources sur votre cluster GKE.

Étape de validation 1

1. Obtenez la liste des services :

kubectl get services

Un service pour l'application de chatbot devrait 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 devrait toujours répondre à l'aide de l'API Gemini (comme configuré dans Cloud Run).

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

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

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 :
   • Utilisez design_infra pour générer le fichier YAML du déploiement et du service vLLM.
   • Mettez à 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.
   • Demandez une confirmation pour appliquer les modifications.
3. Répondez avec yes pour appliquer les modifications.

Étape 2 : Valider

1. Obtenez à nouveau la liste des pods :

kubectl get pods

Vous devriez maintenant voir les 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 le modèle en raison de sa grande taille. 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, redirigez à nouveau le service de chatbot si nécessaire et testez-le. Il devrait maintenant être optimisé par votre modèle Gemma auto-hébergé.

7. Effectuer un nettoyage

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

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

cd terraform
./deploy.sh demo step1 destroy

De plus, vous pouvez 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 les 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 à migrer une charge de travail vers GKE à l'aide d'un agent, du langage naturel et de MCP.