Intent to Infrastructure: Agent-Driven Migration to GKE

1. Introduzione

In questo codelab imparerai a utilizzare un agente AI per eseguire automaticamente una migrazione complessa dell'infrastruttura. Anziché scrivere manualmente i manifest Kubernetes o eseguire script di automazione, esprimerai la tua intenzione in linguaggio naturale e l'agente utilizzerà il server Model Context Protocol (MCP) e Gemini Cloud Assist per generare e applicare la configurazione.

Importante: questo codelab mette in evidenza il server MCP di Gemini Cloud Assist (GCA), attualmente in anteprima privata. Puoi comunque procedere con il codelab anche se non hai accesso all'insieme completo di funzionalità. Tuttavia, se non ti è stato concesso l'accesso alle funzionalità di mutazione (in particolare allo strumento invoke_operation), l'agente non sarà in grado di applicare automaticamente le modifiche. In questo caso, dovrai applicare manualmente i manifest Kubernetes generati. Contatta il team dedicato all'account per ulteriori informazioni.

Funzionalità del server MCP di GCA

Il server MCP di GCA fornisce all'agente diversi strumenti specializzati:

• ask_cloud_assist: questa è l'interfaccia principale per l'assistenza di Google Cloud Platform e per l'agente Gemini Cloud Assist. Tutte le funzionalità di Gemini Cloud Assist sono accessibili tramite questo strumento, che comprende le funzionalità degli altri strumenti MCP.
• design_infra: supporta i flussi di lavoro per la progettazione e l'architettura dell'infrastruttura su Google Cloud Platform.
• investigate_issue: supporta i flussi di lavoro per la risoluzione dei problemi in Google Cloud. Può eseguire una risoluzione rapida dei problemi o una risoluzione più approfondita tramite una risorsa di indagine.
• invoke_operation: supporta i flussi di lavoro per la creazione, l'aggiornamento e l'eliminazione delle risorse in Google Cloud. Questo strumento è funzionale solo quando le azioni dell'agente sono abilitate. Le operazioni di scrittura in Gemini Cloud Assist possono essere eseguite solo tramite la chiamata di questo strumento.
• optimize_costs: supporta i flussi di lavoro per l'analisi, il monitoraggio e l'ottimizzazione dei costi di Google Cloud. Fornisce analisi dettagliate delle spese e identifica le opportunità di efficienza dei costi trovando risorse inattive o sottoutilizzate.

Inizierai con un ambiente preconfigurato con un cluster GKE e un modello scaricato. Poi utilizzerai gemini-cli per chiedere all'agente di eseguire la migrazione di un carico di lavoro da Cloud Run a GKE e di avviare un'istanza di inferenza Gemma con vLLM utilizzando il modello preconfigurato nel bucket di archiviazione.

In questo lab proverai a:

• Preconfigurare un cluster GKE e scaricare un modello Gemma utilizzando Terraform.
• Configurare gemini-cli con regole dell'agente e un server MCP.
• Utilizzare un prompt specifico in linguaggio naturale per chiedere all'agente di eseguire la migrazione e il deployment completi.
• Verificare il deployment eseguito dall'agente.

Che cosa ti serve

• Un browser web come Chrome.
• Un progetto Google Cloud con la fatturazione abilitata.
• Un token Hugging Face (necessario per scaricare il modello Gemma durante la fase di preconfigurazione).

Questo codelab è rivolto a sviluppatori di tutti i livelli, inclusi i principianti.

Durata stimata: 45-60 minuti.

2. Prima di iniziare

Crea o seleziona un progetto Google Cloud

1. Nella console Google Cloud, seleziona o crea un progetto Google Cloud.
2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud.

Avvia Cloud Shell

1. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.
2. Verifica l'autenticazione:

gcloud auth list

3. Conferma il progetto:

gcloud config get project

4. Impostalo se necessario:

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

Abilita API

Esegui questo comando per abilitare tutte le API richieste:

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

Inoltre, abilita il servizio MCP di Gemini Cloud Assist:

gcloud beta services mcp enable geminicloudassist.googleapis.com

3. Preconfigura l'ambiente

In questo passaggio preparerai l'ambiente creando un'immagine chatbot personalizzata, creando il cluster GKE e scaricando il modello Gemma in un bucket Cloud Storage.

Spesso, le organizzazioni iniziano con l'API Gemini, ma in un secondo momento decidono di eseguire la migrazione a un modello self-hosted per un maggiore controllo, personalizzazione o per utilizzare una versione ottimizzata specifica per la loro attività. In questo codelab, utilizziamo Gemma come esempio di un potente modello open che puoi ospitare autonomamente su GKE. La preconfigurazione in un bucket Cloud Storage lo rende disponibile per l'utilizzo da parte del nostro cluster.

Scarica gli asset demo

Clona la cartella specifica dal repository 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

Crea l'immagine del chatbot

Prima di eseguire il provisioning dell'infrastruttura, devi creare l'immagine del chatbot personalizzata ed eseguirne il push in Artifact Registry. Questa immagine verrà utilizzata da Cloud Run nel passaggio successivo.

1. Crea un repository Artifact Registry denominato chatbot-repo in asia-southeast1:

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

2. Vai alla directory src:

   cd src
   

3. Crea ed esegui il push dell'immagine utilizzando Cloud Build:

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

4. Torna alla radice del progetto:

   cd ..
   

Esegui il provisioning dell'infrastruttura di base

Vai alla directory terraform ed esegui il passaggio 1 per creare il cluster GKE.

cd terraform
./deploy.sh demo step1 apply

Nota: se ricevi un errore "Autorizzazione negata" durante l'esecuzione di deploy.sh, potresti doverlo rendere eseguibile eseguendo chmod +x deploy.sh.

Questo script utilizza Terraform per eseguire il provisioning dell'infrastruttura di base. Crea il VPC, il cluster GKE, gli account di servizio ed esegue il deployment del servizio Cloud Run iniziale utilizzando l'immagine del chatbot appena creata.

Durante la procedura, Terraform visualizzerà il piano e ti chiederà di confermare. Dovrai digitare yes per approvare e procedere:

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

Il completamento dell'intera procedura può richiedere 15-20 minuti.

Al termine del deployment, cerca cloud_run_url negli output di Terraform stampati nel terminale. Fai clic sull'URL per aprire il chatbot nel browser. Ora puoi interagire con il chatbot, che al momento è in esecuzione con Gemini 2.5 Flash.

Scarica il modello

In questo passaggio, preconfigureremo il modello Gemma in un bucket Cloud Storage. Anche se inizieremo con l'API Gemini gestita, potresti scegliere di eseguire un modello personalizzato ottimizzato o un altro modello open personalizzato. In alternativa, potresti semplicemente voler mantenere l'esecuzione del modello gestita all'interno del tuo cluster per motivi di sicurezza o conformità. La preconfigurazione del modello qui ci prepara alla migrazione dall'API Gemini gestita a un modello self-hosted su GKE.

Esegui il passaggio 2 per scaricare il modello Gemma nel bucket GCS. Avrai bisogno del tuo token Hugging Face. Questa procedura viene eseguita sul cluster GKE e richiede circa 15 minuti (o più a seconda del traffico) per scaricare il modello da Hugging Face e caricarlo nel bucket per un utilizzo successivo.

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

Questo comando Terraform crea un job Kubernetes sul cluster GKE per gestire il download. Lo script Terraform rimarrà attivo finché il job è in esecuzione.

Se vuoi monitorare l'avanzamento da un'altra sessione della shell o verificare che sia stato completato dopo l'esecuzione, puoi eseguire:

kubectl get jobs

4. Configura l'agente e l'MCP

Ora configureremo l'agente che eseguirà la migrazione. Utilizzeremo gemini-cli e lo doteremo di regole per interagire con l'ambiente.

Il server MCP di Gemini Cloud Assist (GCA) è un componente fondamentale di questo flusso. Funge da ponte tra l'agente lato client e Google Cloud, consentendogli di eseguire indagini, generare piani (come i comandi gcloud e kubectl) e applicare le modifiche direttamente alle risorse nel progetto Cloud.

Assicurati di aver ricevuto un ruolo che consenta di chiamare gli strumenti MCP, ad esempio roles/geminicloudassist.user. Se in un secondo momento riscontri problemi di autorizzazione, consulta la documentazione sulla configurazione dei ruoli IAM per Cloud Assist.

Per istruzioni più dettagliate sull'integrazione di Gemini Cloud Assist con strumenti di terze parti, consulta la documentazione Integra Gemini Cloud Assist con strumenti di terze parti utilizzando MCP.

Installa l'estensione Gemini Cloud Assist

1. Esegui l'autenticazione tramite le Credenziali predefinite dell'applicazione (ADC) eseguendo:

gcloud auth application-default login

2. Installa il server MCP come estensione di Gemini CLI:

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

Nota: questo comando installa sia il server MCP sia una competenza specializzata. La competenza aiuta Gemini CLI a comprendere i contesti appropriati in cui utilizzare gli strumenti di Cloud Assist.

3. Verifica che la competenza sia stata installata correttamente: avvia gemini ed esegui il seguente comando per elencare le competenze attive:

/skills list

Verifica che nell'elenco sia presente la competenza relativa a Gemini Cloud Assist. Digita exit per tornare al prompt di Cloud Shell.

Abilita le mutazioni in Gemini Cloud Assist

Per consentire all'agente di applicare le modifiche all'infrastruttura, devi abilitare le funzionalità di mutazione nella UI di Gemini Cloud Assist.

1. Apri la barra laterale di Gemini Assist facendo clic sul logo di Gemini in alto a destra nella finestra della console Google Cloud.
   
   
2. Abilita le API necessarie elencate nella barra laterale.
   
   
3. Vai alle impostazioni nella barra laterale e seleziona "Abilita Cloud Assist per eseguire azioni".
   
   
   

Configura le regole dell'agente

La directory del progetto include un file gemini.md personalizzato nella radice della cartella (intent-to-infrastructure). Questo file contiene regole che guidano l'agente nell'utilizzo degli strumenti corretti.

Verifica che questo file esista nella directory. Devi eseguire gemini da questa directory in modo che abbia accesso ai file Terraform, al codice dell'applicazione e al file di regole gemini.md.

5. Passaggio 1: esegui la migrazione del chatbot a GKE

Ora utilizzeremo l'agente per eseguire la prima parte della migrazione: spostare l'applicazione chatbot da Cloud Run a GKE.

1. Avvia gemini dalla radice della directory intent-to-infrastructure (assicurandoti che abbia accesso a gemini.md).
2. Innanzitutto, chiediamo all'agente di esplorare il progetto per comprendere l'applicazione e l'infrastruttura. Digita il seguente prompt:

Tell me about the app and infrastructure in this project

L'agente dovrebbe leggere i file nella directory e fornirti una panoramica dell'applicazione chatbot e della configurazione di Terraform.

3. Ora, utilizza il seguente prompt per chiedere all'agente di eseguire la migrazione.

Convert my Cloud Run service to the equivalent on GKE.

4. L'agente dovrebbe:
   • Utilizzare lo strumento ask_cloud_assist per comprendere il contesto.
   • Utilizzare lo strumento design_infra per generare il file YAML di Kubernetes per l'applicazione chatbot.
   • Chiedere: "Vuoi procedere con l'applicazione di questa configurazione?"

Nota: quando gemini tenta di utilizzare uno strumento per la prima volta, ti chiederà l'autorizzazione ad accedere agli strumenti forniti dal server MCP. Seleziona Consenti per consentire all'agente di procedere.

5. Rispondi con yes per applicare le modifiche. L'agente utilizzerà invoke_operation per eseguire il deployment delle risorse nel cluster GKE.

Verifica il passaggio 1

1. Recupera l'elenco dei servizi:

kubectl get services

Dovresti vedere un servizio per l'applicazione chatbot in esecuzione.

2. Esegui il port forwarding del servizio per accedere al chatbot:

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

(Nota: sostituisci

chatbot-service

con il nome effettivo del servizio generato dall'agente, se diverso).

Prova il chatbot. Dovrebbe comunque rispondere utilizzando l'API Gemini (come è stato configurato in Cloud Run).

6. Passaggio 2: esegui il deployment di Gemma tramite vLLM e riconnettiti

In questo passaggio, utilizzeremo l'agente per eseguire il deployment di un modello Gemma self-hosted su GKE e ricollegare la nostra applicazione.

1. Nella stessa sessione gemini, digita il seguente prompt:

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'agente dovrebbe:
   • Utilizzare design_infra per generare il file YAML per il deployment e il servizio vLLM.
   • Aggiornare il file YAML del deployment del chatbot per modificare le variabili di ambiente (o la configurazione) in modo che puntino al nuovo servizio vLLM anziché all'API Gemini.
   • Chiedere la conferma per applicare le modifiche.
3. Rispondi con yes per applicare le modifiche.

Verifica il passaggio 2

1. Recupera di nuovo l'elenco dei pod:

kubectl get pods

Ora dovresti vedere i pod sia per il chatbot sia per vLLM.

Nota: anche se il pod vLLM è nello stato Running, possono essere necessari fino a 10 minuti prima che il server carichi completamente i pesi del modello dal bucket di archiviazione e inizi a pubblicare a causa delle grandi dimensioni del modello. Puoi monitorare l'avanzamento del caricamento controllando i log:

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

2. Quando vLLM è pronto, esegui di nuovo il port forwarding del servizio chatbot, se necessario, e provalo. Ora dovrebbe essere basato sul modello Gemma self-hosted.

7. Elimina

Per evitare addebiti continui sul tuo account Google Cloud, elimina le risorse create durante questo codelab.

Esegui il comando destroy per l'infrastruttura di base:

cd terraform
./deploy.sh demo step1 destroy

Inoltre, se vuoi liberare spazio nell'ambiente locale, puoi disinstallare o disattivare l'estensione Gemini Cloud Assist. Utilizza gemini extensions uninstall o gemini extensions disable seguito dal nome dell'estensione.

8. Passaggi successivi

Per saperne di più su Gemini Cloud Assist e sulle funzionalità avanzate, consulta queste risorse:

• Risolvi i problemi relativi alle indagini di Cloud Assist
• Configura la modalità proattiva

9. Complimenti

Complimenti! Hai eseguito correttamente la migrazione di un carico di lavoro a GKE basata su agente utilizzando il linguaggio naturale e l'MCP.