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 automáticamente una migración de infraestructura compleja. En lugar de escribir manifiestos de Kubernetes de forma manual 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, 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. Para obtener más información, comunícate con tu equipo de cuentas.

Funciones del servidor de MCP de GCA

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

• ask_cloud_assist: 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, y abarca la funcionalidad de las otras 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 del gasto y, además, identifica oportunidades para mejorar la eficiencia de los costos mediante la búsqueda de 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 solicitarle 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 preconfigurado en tu bucket de almacenamiento.

Actividades

• Preconfigura un clúster de GKE y descarga un modelo de Gemma con Terraform.
• Configura gemini-cli con reglas de agente 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 preconfiguración).

Este codelab está dirigido a desarrolladores de todos los niveles, incluidos principiantes.

Duración estimada: 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úralo si es necesario:

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

Habilita las 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. Preconfigura el entorno

En este paso, prepararás el entorno mediante la compilación de una imagen de chatbot personalizada, la creación del clúster de GKE y la descarga del 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 un mayor control, personalización o para 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 en GKE. La preconfiguración 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 personalizada 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 en Gemini 2.5 Flash.

Descarga el modelo

En este paso, preconfiguraremos el modelo de Gemma en un bucket de Cloud Storage. Si bien comenzaremos con la API de Gemini administrada, puedes elegir ejecutar un modelo personalizado ajustado o cualquier otro modelo abierto personalizado. Como alternativa, es posible que solo desees mantener la ejecución del modelo administrada dentro de tu propio clúster por motivos de seguridad o cumplimiento. La preconfiguración del modelo aquí nos prepara para 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 deseas supervisar el progreso desde una sesión de shell diferente 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 tienes problemas de permisos más adelante, 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 mediante 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 lo siguiente:

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 Gemini CLI a comprender los contextos adecuados en los que se deben usar las herramientas de Cloud Assist.

3. Verifica que la habilidad se haya instalado correctamente: Inicia gemini y ejecuta el siguiente comando para obtener una lista de las habilidades 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 aparecen en la barra lateral.
   
   
3. Navega a la configuración en la barra lateral y marca "Habilitar Cloud Assist para ejecutar acciones".
   
   
   

Configura las 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 usar 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 gemini.md.

5. Paso 1: Migra el chatbot a GKE

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

1. Inicia gemini desde la raíz del directorio intent-to-infrastructure (asegurándote 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 darte una descripción general de la aplicación del 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:
   • Usar la herramienta ask_cloud_assist para comprender el contexto
   • Usar la herramienta design_infra para generar el YAML de Kubernetes para la aplicación del chatbot
   • Preguntar: "¿Quieres continuar con la aplicación de esta configuración?"

Nota: Cuando gemini intente usar una herramienta por primera vez, te pedirá permiso para acceder a las herramientas que proporciona el servidor de MCP. Debes seleccionar Permitir para habilitar que el agente continúe.

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

Verifica el paso 1

1. Obtén la lista de servicios:

kubectl get services

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

2. Redirige el servicio para acceder al chatbot:

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

(Nota: Reemplaza

chatbot-service

por el nombre real del servicio que generó el agente si es diferente).

Prueba el chatbot. Aún debería responder con la API de Gemini (como se configuró en Cloud Run).

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

En este paso, usaremos el agente para implementar un modelo de Gemma autoalojado 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:
   • Usar design_infra para generar YAML para la implementación y el servicio de vLLM
   • Actualizar el YAML de implementación del chatbot para cambiar las variables de entorno (o la configuración) para que apunten al nuevo servicio de vLLM en lugar de la API de Gemini
   • Pedir 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 pods para el chatbot y 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 entregarlos debido al gran tamaño del modelo. Puedes supervisar el progreso de carga si verificas los registros:

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

2. Una vez que vLLM esté listo, vuelve a redireccionar el servicio del chatbot si es necesario y pruébalo. Ahora debería estar potenciado por tu modelo de Gemma autoalojado.

7. Limpieza

Para evitar cargos continuos en tu cuenta de Google Cloud, borra los recursos creados 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
• Configura el modo proactivo

9. Felicitaciones

¡Felicitaciones! Realizaste correctamente una migración de una carga de trabajo a GKE con un agente usando lenguaje natural y MCP.