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 Model Context Protocol (MCP) e il server 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 al set completo di funzionalità. Tuttavia, se non ti è stato concesso l'accesso alle funzionalità di mutazione (in particolare allo strumento invoke_operation), l'agente non potrà 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 GCA

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

• ask_cloud_assist: questa è l'interfaccia principale per l'assistenza Google Cloud Platform e per l'agente Gemini Cloud Assist. Tutte le funzionalità di Gemini Cloud Assist sono accessibili tramite questo strumento, che include 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 dei problemi rapida o 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 sono attive le Azioni dell'agente. Le operazioni di scrittura in Gemini Cloud Assist possono essere eseguite solo tramite l'invocazione di questo strumento.
• optimize_costs: supporta i flussi di lavoro per l'analisi, il monitoraggio e l'ottimizzazione dei costi di Google Cloud. Fornisce suddivisioni dettagliate della spesa e identifica le opportunità di efficienza dei costi individuando le risorse inattive o sottoutilizzate.

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

In questo lab proverai a:

• Organizza un cluster GKE e scarica un modello Gemma utilizzando Terraform.
• Configura gemini-cli con regole dell'agente e un server MCP.
• Utilizza un prompt in linguaggio naturale specifico per indicare all'agente di eseguire la migrazione e il deployment completi.
• Verifica 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 (obbligatorio per scaricare il modello Gemma durante la fase di staging).

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 Gemini Cloud Assist:

gcloud beta services mcp enable geminicloudassist.googleapis.com

3. Organizzare 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 seguito decidono di eseguire la migrazione a un modello self-hosted per un maggiore controllo, personalizzazione o per utilizzare una versione ottimizzata specifica per la propria attività. In questo codelab, utilizziamo Gemma come esempio di un potente modello aperto che puoi ospitare autonomamente su GKE. Il suo staging 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 immagine del chatbot

Prima di eseguire il provisioning dell'infrastruttura, devi creare l'immagine del chatbot personalizzato ed eseguirne il push su 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 l'errore "Autorizzazione negata" durante l'esecuzione di deploy.sh, potrebbe essere necessario renderlo eseguibile eseguendo chmod +x deploy.sh.

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

Durante il processo, Terraform mostrerà il piano e chiederà la conferma. Per approvare e procedere, dovrai digitare yes:

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

L'intera procedura può richiedere 15-20 minuti.

Una volta completato il 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 utilizza Gemini 2.5 Flash.

Scaricare il modello

In questo passaggio, prepareremo 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 source personalizzato. In alternativa, potresti semplicemente voler mantenere l'esecuzione del modello gestita all'interno del tuo cluster per motivi di sicurezza o conformità. Il modello di gestione temporanea 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. Questo processo viene eseguito sul tuo cluster GKE e richiede circa 15 minuti (o più a seconda del traffico) per scaricare il modello da Hugging Face e caricarlo nel tuo 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. Configurare l'agente e 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 del tuo 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 Integrare Gemini Cloud Assist con strumenti di terze parti utilizzando MCP.

Installare 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 Gemini CLI:

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

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

3. Verifica che la skill sia stata installata correttamente: avvia gemini ed esegui questo comando per elencare le skill attive:

/skills list

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

Attiva le mutazioni in Gemini Cloud Assist

Per consentire all'agente di applicare modifiche alla tua infrastruttura, devi abilitare le funzionalità di mutazione nell'interfaccia utente di Gemini Cloud Assist.

1. Apri la barra laterale di Gemini Assist facendo clic sul logo 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".
   
   
   

Configurare 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 a utilizzare gli strumenti corretti.

Verifica che questo file esista nella tua 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: lo spostamento dell'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 deve leggere i file nella directory e fornirti una panoramica dell'applicazione chatbot e della configurazione 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 deve:
   • Utilizza lo strumento ask_cloud_assist per comprendere il contesto.
   • Utilizza lo strumento design_infra per generare il file YAML di Kubernetes per l'applicazione chatbot.
   • Chiedi: "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. Per consentire all'agente di procedere, seleziona Consenti.

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

Verifica passaggio 1

1. Recupera l'elenco dei servizi:

kubectl get services

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

2. Inoltra la porta 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).

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

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

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

1. Nella stessa sessione gemini, inserisci 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 deve:
   • Utilizza design_infra per generare YAML per il deployment e il servizio vLLM.
   • Aggiorna il file YAML di deployment del chatbot per modificare le variabili di ambiente (o la configurazione) in modo che puntino al nuovo servizio vLLM anziché all'API Gemini.
   • Chiedi la conferma per applicare le modifiche.
3. Rispondi con yes per applicare le modifiche.

Verifica passaggio 2

1. Recupera di nuovo l'elenco dei pod:

kubectl get pods

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

Nota:anche dopo che il pod vLLM si trova nello stato Running, potrebbero essere necessari fino a 10 minuti prima che il server carichi completamente i pesi del modello dal bucket di archiviazione e inizi a pubblicarli 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 testalo. Ora dovrebbe essere alimentato dal tuo modello Gemma autogestito.

7. Elimina

Per evitare addebiti continui al 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, puoi disinstallare o disattivare l'estensione Gemini Cloud Assist se vuoi liberare spazio nell'ambiente locale. Utilizza gemini extensions uninstall o gemini extensions disable seguito dal nome dell'estensione.

8. Passaggi successivi

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

• Risolvere i problemi relativi a Cloud Assist Investigations
• Configurare la modalità Proattiva

9. Complimenti

Complimenti! Hai eseguito correttamente una migrazione basata su agent di un carico di lavoro a GKE utilizzando il linguaggio naturale e MCP.