Intenção para infraestrutura: migração orientada por agente para o GKE

1. Introdução

Neste codelab, você vai aprender a usar um agente de IA para realizar uma migração complexa de infraestrutura de forma automática. Em vez de escrever manualmente manifestos do Kubernetes ou executar scripts de automação, você vai expressar sua intenção em linguagem natural, e o agente vai usar o Protocolo de Contexto de Modelo (MCP) e o servidor do Gemini Cloud Assist para gerar e aplicar a configuração.

Importante:este codelab destaca o servidor MCP do Gemini Cloud Assist (GCA), que está em prévia particular. Você ainda pode continuar com o codelab mesmo que não tenha acesso ao conjunto completo de atributos. No entanto, se você não tiver acesso aos recursos de mutação (especificamente à ferramenta invoke_operation), o agente não poderá aplicar as mudanças automaticamente. Nesse caso, você precisará aplicar manualmente os manifestos do Kubernetes gerados. Entre em contato com sua equipe de conta para mais informações.

Recursos do servidor MCP do GCA

O servidor MCP do GCA oferece várias ferramentas especializadas ao agente:

• ask_cloud_assist: é a interface principal para assistência do Google Cloud Platform e para o agente do Gemini Cloud Assist. Todas as funcionalidades do Gemini Cloud Assist estão acessíveis por essa ferramenta, que abrange as funcionalidades das outras ferramentas do MCP.
• design_infra: oferece suporte a fluxos de trabalho para projetar e arquitetar infraestrutura no Google Cloud Platform.
• investigate_issue: oferece suporte a fluxos de trabalho para solução de problemas no Google Cloud. Ela pode fazer uma solução de problemas rápida ou mais detalhada usando um recurso de investigação.
• invoke_operation: oferece suporte a fluxos de trabalho para criar, atualizar e excluir recursos no Google Cloud. Essa ferramenta só funciona quando as ações do agente estão ativadas. As operações de gravação no Gemini Cloud Assist só podem ser executadas com a invocação dessa ferramenta.
• optimize_costs: oferece suporte a fluxos de trabalho para analisar, rastrear e otimizar os custos do Google Cloud. Ele fornece detalhamentos de gastos e identifica oportunidades de eficiência de custos ao encontrar recursos ociosos ou subutilizados.

Você vai começar com um ambiente pré-preparado com um cluster do GKE e um modelo baixado. Em seguida, você vai usar o gemini-cli para pedir ao agente que migre uma carga de trabalho do Cloud Run para o GKE e inicie uma instância de inferência da Gemma com o vLLM usando o modelo preparado no bucket de armazenamento.

Atividades deste laboratório

• Organizar um cluster do GKE e baixar um modelo da Gemma usando o Terraform.
• Configure gemini-cli com regras de agente e um servidor MCP.
• Use um comando específico de linguagem natural para instruir o agente a realizar a migração e a implantação completas.
• Verifique a implantação realizada pelo agente.

O que é necessário

• Um navegador da Web, como o Chrome.
• Ter um projeto do Google Cloud com o faturamento ativado.
• Um token do Hugging Face (obrigatório para fazer o download do modelo Gemma durante a fase de staging).

Este codelab é destinado a desenvolvedores de todos os níveis, incluindo iniciantes.

Duração estimada:45 a 60 minutos.

2. Antes de começar

Criar ou selecionar um projeto do Google Cloud

1. No Console do Google Cloud, selecione ou crie um projeto na nuvem do Google Cloud.
2. Verifique se o faturamento está ativado para seu projeto do Cloud.

Iniciar o Cloud Shell

1. Clique em Ativar o Cloud Shell na parte de cima do console do Google Cloud.
2. Verificar a autenticação:

gcloud auth list

3. Confirme seu projeto:

gcloud config get project

4. Defina, se necessário:

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

Ativar APIs

Execute este comando para ativar todas as APIs necessárias:

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

Além disso, ative o serviço MCP do Gemini Cloud Assist:

gcloud beta services mcp enable geminicloudassist.googleapis.com

3. Preparar o ambiente

Nesta etapa, você vai preparar o ambiente criando uma imagem personalizada de chatbot, criando o cluster do GKE e fazendo o download do modelo Gemma para um bucket do Cloud Storage.

Muitas vezes, as organizações começam com a API Gemini, mas depois decidem migrar para um modelo autohospedado para ter mais controle, personalização ou usar uma versão refinada específica para os negócios. Neste codelab, usamos o Gemma como exemplo de um modelo aberto avançado que você pode hospedar no GKE. Ao fazer isso em um bucket do Cloud Storage, ele fica disponível para uso pelo nosso cluster.

Baixar recursos de demonstração

Clone a pasta específica do repositório do 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

Criar imagem de chatbot

Antes de provisionar a infraestrutura, crie a imagem do chatbot personalizado e envie para o Artifact Registry. Essa imagem será usada pelo Cloud Run na próxima etapa.

1. Crie um repositório do Artifact Registry chamado chatbot-repo em asia-southeast1:

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

2. Navegue até o diretório src:

   cd src
   

3. Crie e envie a imagem usando o Cloud Build:

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

4. Volte para a raiz do projeto:

   cd ..
   

Provisionar infraestrutura base

Navegue até o diretório terraform e execute a etapa 1 para criar o cluster do GKE.

cd terraform
./deploy.sh demo step1 apply

Observação:se você receber um erro "Permissão negada" ao executar deploy.sh, talvez seja necessário torná-lo executável executando chmod +x deploy.sh.

Esse script usa o Terraform para provisionar a infraestrutura de base. Ele cria a VPC, o cluster do GKE, as contas de serviço e implanta o serviço inicial do Cloud Run usando a imagem do chatbot que você acabou de criar.

Durante o processo, o Terraform vai mostrar o plano e pedir confirmação. Digite yes para aprovar e continuar:

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

Todo o processo pode levar de 15 a 20 minutos.

Quando a implantação for concluída, procure o cloud_run_url nas saídas do Terraform impressas no terminal. Clique no URL para abrir o chatbot no navegador. Agora você pode interagir com o chatbot, que está sendo executado com o Gemini 2.5 Flash.

Baixar o modelo

Nesta etapa, vamos preparar o modelo Gemma em um bucket do Cloud Storage. Embora estejamos começando com a API Gemini gerenciada, você pode executar um modelo personalizado refinado ou outro modelo aberto personalizado. Ou talvez você queira manter a execução do modelo gerenciada no seu próprio cluster por motivos de segurança ou compliance. Ao fazer o teste do modelo aqui, nos preparamos para a migração da API Gemini gerenciada para um modelo autohospedado no GKE.

Execute a etapa 2 para fazer o download do modelo Gemma no seu bucket do GCS. Você vai precisar do seu token do Hugging Face. Esse processo é executado no cluster do GKE e leva cerca de 15 minutos (ou mais, dependendo do tráfego) para fazer o download do modelo do Hugging Face e o upload para o bucket para uso posterior.

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

Esse comando do Terraform cria um job do Kubernetes no cluster do GKE para processar o download. O script do Terraform vai permanecer ativo enquanto o job estiver em execução.

Se você quiser monitorar o progresso de uma sessão de shell diferente ou verificar se ele foi concluído após a execução, execute:

kubectl get jobs

4. Configurar o agente e o MCP

Agora vamos configurar o agente que vai realizar a migração. Vamos usar o gemini-cli e equipá-lo com regras para interagir com o ambiente.

O servidor MCP do Gemini Cloud Assist (GCA) é um componente essencial desse fluxo. Ele funciona como uma ponte entre o agente do lado do cliente e o Google Cloud, permitindo que ele faça investigações, gere planos (como comandos gcloud e kubectl) e aplique mudanças diretamente aos recursos no projeto do Google Cloud.

Verifique se você recebeu um papel que permite chamar ferramentas do MCP, como roles/geminicloudassist.user. Se você encontrar problemas de permissão mais tarde, consulte a documentação sobre como configurar papéis do IAM para o Cloud Assist.

Para instruções mais detalhadas sobre como integrar o Gemini Cloud Assist a ferramentas de terceiros, consulte a documentação Integrar o Gemini Cloud Assist a ferramentas de terceiros usando o MCP.

Instalar a extensão do Gemini Cloud Assist

1. Autentique-se usando o Application Default Credentials (ADC) executando:

gcloud auth application-default login

2. Instale o servidor MCP como uma extensão da CLI do Gemini:

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

Observação:esse comando instala o servidor MCP e uma habilidade especializada. A habilidade ajuda a CLI do Gemini a entender os contextos adequados para usar as ferramentas do Cloud Assist.

3. Verifique se a habilidade foi instalada com sucesso: inicie o gemini e execute o seguinte comando para listar as habilidades ativas:

/skills list

Verifique se a habilidade relacionada ao Gemini Cloud Assist aparece na lista. Digite exit para voltar ao prompt do Cloud Shell.

Ativar mutações no Gemini Cloud Assist

Para permitir que o agente aplique mudanças na sua infraestrutura, ative os recursos de mutação na interface do Gemini Cloud Assist.

1. Abra a barra lateral do Gemini Assist clicando no logotipo do Gemini na parte superior direita da janela do console do Google Cloud.
   
   
2. Ative as APIs necessárias listadas na barra lateral.
   
   
3. Acesse as configurações na barra lateral e marque "Ativar o Cloud Assist para executar ações".
   
   
   

Configurar regras de agente

O diretório do projeto inclui um arquivo gemini.md personalizado na raiz da pasta (intent-to-infrastructure). Esse arquivo contém regras que orientam o agente a usar as ferramentas corretas.

Verifique se esse arquivo existe no seu diretório. Execute gemini nesse diretório para que ele tenha acesso aos arquivos do Terraform, ao código do aplicativo e ao arquivo de regras gemini.md.

5. Etapa 1: migrar o chatbot para o GKE

Agora vamos usar o agente para realizar a primeira parte da migração: mover o aplicativo de chatbot do Cloud Run para o GKE.

1. Inicie gemini na raiz do diretório intent-to-infrastructure, garantindo que ele tenha acesso a gemini.md.
2. Primeiro, vamos pedir ao agente para explorar o projeto e entender o aplicativo e a infraestrutura. Insira o seguinte comando:

Tell me about the app and infrastructure in this project

O agente vai ler os arquivos no diretório e dar uma visão geral do aplicativo de chatbot e da configuração do Terraform.

3. Agora, use o comando a seguir para instruir o agente a realizar a migração.

Convert my Cloud Run service to the equivalent on GKE.

4. O agente precisa:
   • Use a ferramenta ask_cloud_assist para entender o contexto.
   • Use a ferramenta design_infra para gerar o YAML do Kubernetes para o aplicativo de chatbot.
   • Pergunte: "Você quer continuar aplicando essa configuração?"

Observação:quando o gemini tenta usar uma ferramenta pela primeira vez, ele pede sua permissão para acessar as ferramentas fornecidas pelo servidor MCP. Selecione Permitir para que o agente possa continuar.

5. Responda com yes para aplicar as mudanças. O agente vai usar invoke_operation para implantar os recursos no cluster do GKE.

Etapa 1 da verificação

1. Confira a lista de serviços:

kubectl get services

Você vai ver um serviço em execução para o aplicativo de chatbot.

2. Encaminhe a porta do serviço para acessar o chatbot:

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

Observação: substitua

chatbot-service

com o nome real do serviço gerado pelo agente, se for diferente.

Teste o chatbot. Ele ainda vai responder usando a API Gemini (como foi configurado no Cloud Run).

6. Etapa 2: implante a Gemma usando o vLLM e o Reconnect

Nesta etapa, vamos usar o agente para implantar um modelo do Gemma autohospedado no GKE e reconectar nosso aplicativo a ele.

1. Na mesma sessão gemini, insira o seguinte comando:

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. O agente precisa:
   • Use design_infra para gerar YAML para a implantação e o serviço do vLLM.
   • Atualize o YAML de implantação do chatbot para mudar as variáveis de ambiente (ou configuração) e apontar para o novo serviço vLLM em vez da API Gemini.
   • Peça confirmação para aplicar as mudanças.
3. Responda com yes para aplicar as mudanças.

Verificar etapa 2

1. Abra a lista de pods novamente:

kubectl get pods

Agora você vai ver pods para o chatbot e o vLLM.

Observação:mesmo depois que o pod vLLM estiver no estado Running, pode levar até 10 minutos para o servidor carregar totalmente os pesos do modelo do bucket de armazenamento e começar a atender devido ao grande tamanho do modelo. Para monitorar o progresso do carregamento, verifique os registros:

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

2. Quando o vLLM estiver pronto, encaminhe a porta do serviço de chatbot novamente, se necessário, e teste-o. Agora ele vai ser alimentado pelo seu modelo Gemma auto-hospedado.

7. Limpeza

Para evitar cobranças contínuas na sua conta do Google Cloud, exclua os recursos criados durante este codelab.

Execute o comando de exclusão da infraestrutura de base:

cd terraform
./deploy.sh demo step1 destroy

Além disso, você pode desinstalar ou desativar a extensão Gemini Cloud Assist se quiser limpar seu ambiente local. Use gemini extensions uninstall ou gemini extensions disable seguido do nome da extensão.

8. A seguir

Para saber mais sobre o Gemini Cloud Assist e os recursos avançados, confira estes recursos:

• Resolver problemas com as investigações do Cloud Assist
• Configurar o modo proativo

9. Parabéns

Parabéns! Você realizou com sucesso uma migração de uma carga de trabalho para o GKE usando linguagem natural e MCP.