De la intención a la infraestructura: Migración impulsada por agentes a GKE

1. Introducción

En este codelab, aprenderás a usar un agente de IA para realizar una migración de infraestructura compleja de forma automática. En lugar de escribir manualmente manifiestos de Kubernetes o ejecutar secuencias de comandos de automatización, expresarás tu intención en lenguaje natural, y el agente usará el Protocolo de contexto del modelo (MCP) y el servidor de Gemini Cloud Assist para generar y aplicar la configuración por ti.

Importante: En este codelab, se destaca el servidor de MCP de Gemini Cloud Assist (GCA), que actualmente se encuentra en versión preliminar privada. Puedes continuar con el codelab incluso si no tienes acceso al conjunto completo de funciones. Sin embargo, si no se te otorgó acceso a las funciones de mutación (específicamente, a la herramienta invoke_operation), el agente no podrá aplicar los cambios automáticamente. En ese caso, deberás aplicar de forma manual los manifiestos de Kubernetes generados. Comunícate con tu equipo de cuentas para obtener más información.

Funciones del servidor de MCP de GCA

El servidor de MCP de GCA proporciona varias herramientas especializadas al agente:

• ask_cloud_assist: Esta es la interfaz principal para la asistencia de Google Cloud Platform y para el agente de Gemini Cloud Assist. Se puede acceder a todas las funciones de Gemini Cloud Assist a través de esta herramienta, que abarca las funciones de las demás herramientas de MCP.
• design_infra: Admite flujos de trabajo para diseñar y crear la arquitectura de la infraestructura en Google Cloud Platform.
• investigate_issue: Admite flujos de trabajo para solucionar problemas en Google Cloud. Puede realizar una solución de problemas rápida o más profunda a través de un recurso de investigación.
• invoke_operation: Admite flujos de trabajo para crear, actualizar y borrar recursos en Google Cloud. Esta herramienta solo funciona cuando las acciones del agente están habilitadas. Las operaciones de escritura en Gemini Cloud Assist solo se pueden ejecutar a través de la invocación de esta herramienta.
• optimize_costs: Admite flujos de trabajo para analizar, hacer un seguimiento y optimizar los costos de Google Cloud. Proporciona desgloses detallados de la inversión e identifica oportunidades para mejorar la eficiencia de los costos, ya que encuentra recursos inactivos o poco utilizados.

Comenzarás con un entorno preconfigurado con un clúster de GKE y un modelo descargado. Luego, usarás gemini-cli para indicarle al agente que migre una carga de trabajo de Cloud Run a GKE y que inicie una instancia de inferencia de Gemma con vLLM usando el modelo organizado en tu bucket de almacenamiento.

Actividades

• Organiza un clúster de GKE y descarga un modelo de Gemma con Terraform.
• Configura gemini-cli con reglas de agentes y un servidor de MCP.
• Usa una instrucción específica en lenguaje natural para indicarle al agente que realice la migración y la implementación completas.
• Verifica la implementación que realizó el agente.

Requisitos

• Un navegador web, como Chrome
• Un proyecto de Google Cloud con facturación habilitada.
• Un token de Hugging Face (obligatorio para descargar el modelo de Gemma durante la fase de preparación)

Este codelab es para desarrolladores de todos los niveles, incluidos los principiantes.

Duración estimada: De 45 a 60 minutos

2. Antes de comenzar

Crea o selecciona un proyecto de Google Cloud

1. En la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
2. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud.

Inicie Cloud Shell

1. Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud.
2. Verifica la autenticación:

gcloud auth list

3. Confirma tu proyecto:

gcloud config get project

4. Configúrala si es necesario:

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

Habilitar APIs

Ejecuta este comando para habilitar todas las APIs requeridas:

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

Además, habilita el servicio de MCP de Gemini Cloud Assist:

gcloud beta services mcp enable geminicloudassist.googleapis.com

3. Prepara el entorno

En este paso, prepararás el entorno compilando una imagen de chatbot personalizada, creando el clúster de GKE y descargando el modelo de Gemma en un bucket de Cloud Storage.

A menudo, las organizaciones comienzan con la API de Gemini, pero luego deciden migrar a un modelo autoalojado para tener mayor control, personalización o usar una versión ajustada específica para su empresa. En este codelab, usamos Gemma como ejemplo de un modelo abierto potente que puedes alojar por tu cuenta en GKE. Almacenarlo en un bucket de Cloud Storage hace que esté disponible para que lo use nuestro clúster.

Descarga recursos de demostración

Clona la carpeta específica del repositorio de 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

Compila la imagen del chatbot

Antes de aprovisionar la infraestructura, debes compilar la imagen del chatbot personalizado y enviarla a Artifact Registry. Cloud Run usará esta imagen en el siguiente paso.

1. Crea un repositorio de Artifact Registry llamado chatbot-repo en asia-southeast1:

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

2. Navega al directorio src:

   cd src
   

3. Compila y envía la imagen mediante Cloud Build:

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

4. Regresa a la raíz del proyecto:

   cd ..
   

Aprovisiona la infraestructura base

Navega al directorio terraform y ejecuta el paso 1 para crear el clúster de GKE.

cd terraform
./deploy.sh demo step1 apply

Nota: Si recibes un error de "Permiso denegado" cuando ejecutas deploy.sh, es posible que debas ejecutar chmod +x deploy.sh para que se pueda ejecutar.

Esta secuencia de comandos usa Terraform para aprovisionar la infraestructura base. Crea la VPC, el clúster de GKE y las cuentas de servicio, y, luego, implementa el servicio inicial de Cloud Run con la imagen del chatbot que acabas de compilar.

Durante el proceso, Terraform mostrará el plan y solicitará una confirmación. Deberás escribir yes para aprobar y continuar:

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

Todo el proceso puede tardar entre 15 y 20 minutos en completarse.

Una vez que se complete la implementación, busca cloud_run_url en los resultados de Terraform que se imprimieron en la terminal. Haz clic en la URL para abrir el chatbot en tu navegador. Ahora puedes interactuar con el chatbot, que actualmente se ejecuta con Gemini 2.5 Flash.

Descarga el modelo

En este paso, realizaremos el stage del modelo de Gemma en un bucket de Cloud Storage. Si bien comenzaremos con la API de Gemini administrada, puedes optar por ejecutar un modelo personalizado ajustado o cualquier otro modelo abierto personalizado. Como alternativa, es posible que simplemente desees mantener la ejecución del modelo administrada dentro de tu propio clúster por motivos de seguridad o cumplimiento. La preparación del modelo aquí nos permite realizar la migración de la API de Gemini administrada a un modelo autoalojado en GKE.

Ejecuta el paso 2 para descargar el modelo de Gemma en tu bucket de GCS. Necesitarás tu token de Hugging Face. Este proceso se ejecuta en tu clúster de GKE y tardará alrededor de 15 minutos (o más, según el tráfico) en descargar el modelo de Hugging Face y subirlo a tu bucket para usarlo más adelante.

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

Este comando de Terraform crea un trabajo de Kubernetes en tu clúster de GKE para controlar la descarga. La secuencia de comandos de Terraform permanecerá activa mientras se ejecute el trabajo.

Si quieres supervisar el progreso desde otra sesión de shell o verificar que se completó después de la ejecución, puedes ejecutar lo siguiente:

kubectl get jobs

4. Configura el agente y el MCP

Ahora configuraremos el agente que realizará la migración. Usaremos gemini-cli y lo equiparemos con reglas para interactuar con el entorno.

El servidor de MCP de Gemini Cloud Assist (GCA) es un componente fundamental de este flujo. Actúa como un puente entre tu agente del cliente y Google Cloud, lo que le permite realizar investigaciones, generar planes (como los comandos gcloud y kubectl) y aplicar cambios directamente a los recursos de tu proyecto de Cloud.

Asegúrate de que se te haya otorgado un rol que permita llamar a las herramientas de MCP, como roles/geminicloudassist.user. Si más adelante tienes problemas con los permisos, consulta la documentación sobre cómo configurar roles de IAM para Cloud Assist.

Para obtener instrucciones más detalladas sobre cómo integrar Gemini Cloud Assist con herramientas de terceros, consulta la documentación Integra Gemini Cloud Assist con herramientas de terceros usando MCP.

Instala la extensión de Gemini Cloud Assist

1. Para autenticarte a través de las credenciales predeterminadas de la aplicación (ADC), ejecuta el siguiente comando:

gcloud auth application-default login

2. Instala el servidor de MCP como una extensión de Gemini CLI:

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

Nota: Este comando instala el servidor de MCP y una habilidad especializada. La habilidad ayuda a la CLI de Gemini a comprender los contextos adecuados en los que se deben usar las herramientas de Cloud Assist.

3. Verifica que la skill se haya instalado correctamente: Inicia gemini y ejecuta el siguiente comando para enumerar las skills activas:

/skills list

Verifica que veas la habilidad relacionada con Gemini Cloud Assist en la lista. Escribe exit para volver al símbolo del sistema de Cloud Shell.

Habilita las mutaciones en Gemini Cloud Assist

Para permitir que el agente aplique cambios a tu infraestructura, debes habilitar las funciones de mutación en la IU de Gemini Cloud Assist.

1. Para abrir la barra lateral de Gemini Assist, haz clic en el logotipo de Gemini en la parte superior derecha de la ventana de la consola de Google Cloud.
   
   
2. Habilita las APIs necesarias que se indican en la barra lateral.
   
   
3. Navega a la configuración en la barra lateral y marca "Habilitar Cloud Assist para ejecutar acciones".
   
   
   

Configura reglas del agente

El directorio del proyecto incluye un archivo gemini.md personalizado en la raíz de la carpeta (intent-to-infrastructure). Este archivo contiene reglas que guían al agente para que use las herramientas correctas.

Verifica que este archivo exista en tu directorio. Debes ejecutar gemini desde este directorio para que tenga acceso a los archivos de Terraform, al código de la aplicación y al archivo de reglas de gemini.md.

5. Paso 1: Migra el chatbot a GKE

Ahora usaremos el agente para realizar la primera parte de la migración: mover la aplicación de chatbot de Cloud Run a GKE.

1. Inicia gemini desde la raíz del directorio intent-to-infrastructure (asegúrate de que tenga acceso a gemini.md).
2. Primero, pidámosle al agente que explore el proyecto para comprender la aplicación y la infraestructura. Escribe la siguiente instrucción:

Tell me about the app and infrastructure in this project

El agente debe leer los archivos del directorio y brindarte una descripción general de la aplicación de chatbot y la configuración de Terraform.

3. Ahora, usa la siguiente instrucción para indicarle al agente que realice la migración.

Convert my Cloud Run service to the equivalent on GKE.

4. El agente debe hacer lo siguiente:
   • Usa la herramienta ask_cloud_assist para comprender el contexto.
   • Usa la herramienta design_infra para generar el archivo YAML de Kubernetes para la aplicación de chatbot.
   • Pregunta: "¿Quieres continuar y aplicar esta configuración?".

Nota: Cuando gemini intente usar una herramienta por primera vez, te pedirá permiso para acceder a las herramientas proporcionadas por el servidor de MCP. Debes seleccionar Permitir para que el agente pueda continuar.

5. Responde con yes para aplicar los cambios. El agente usará invoke_operation para implementar los recursos en tu clúster de GKE.

Verificación, paso 1

1. Obtén la lista de servicios:

kubectl get services

Deberías ver un servicio en ejecución para la aplicación de chatbot.

2. Redirecciona el puerto del servicio para acceder al chatbot:

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

(Nota: Reemplaza

chatbot-service

con el nombre real del servicio que generó el agente si es diferente

Probar el chatbot Debería seguir respondiendo con la API de Gemini (como se configuró en Cloud Run).

6. Paso 2: Implementa Gemma a través de vLLM y Reconnect

En este paso, usaremos el agente para implementar un modelo de Gemma alojado por el usuario en GKE y volver a conectar nuestra aplicación a él.

1. En la misma sesión de gemini, ingresa la siguiente instrucción:

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. El agente debe hacer lo siguiente:
   • Usa design_infra para generar YAML para la implementación y el servicio de vLLM.
   • Actualiza la implementación del chatbot en YAML para cambiar las variables de entorno (o la configuración) de modo que apunten al nuevo servicio de vLLM en lugar de a la API de Gemini.
   • Solicita confirmación para aplicar los cambios.
3. Responde con yes para aplicar los cambios.

Verifica el paso 2

1. Vuelve a obtener la lista de Pods:

kubectl get pods

Ahora deberías ver los Pods del chatbot y de vLLM.

Nota: Incluso después de que el pod de vLLM esté en el estado Running, el servidor puede tardar hasta 10 minutos en cargar por completo los pesos del modelo desde el bucket de almacenamiento y comenzar a entregar resultados debido al gran tamaño del modelo. Puedes supervisar el progreso de carga verificando los registros:

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

2. Una vez que vLLM esté listo, reenvía el puerto del servicio de chatbot si es necesario y pruébalo. Ahora debería funcionar con tu modelo de Gemma alojado por tu cuenta.

7. Limpieza

Para evitar que se apliquen cargos a tu cuenta de Google Cloud, borra los recursos que creaste durante este codelab.

Ejecuta el comando destroy para la infraestructura base:

cd terraform
./deploy.sh demo step1 destroy

Además, puedes desinstalar o inhabilitar la extensión de Gemini Cloud Assist si deseas limpiar tu entorno local. Usa gemini extensions uninstall o gemini extensions disable seguido del nombre de la extensión.

8. ¿Qué sigue?

Para obtener más información sobre Gemini Cloud Assist y las funciones avanzadas, consulta estos recursos:

• Soluciona problemas con las investigaciones de Cloud Assist
• Cómo configurar el Modo Proactivo

9. Felicitaciones

¡Felicitaciones! Migraste correctamente una carga de trabajo a GKE con un agente controlado por lenguaje natural y MCP.