Instalar o Agent Substrate no GKE

O Agent Substrate executa cargas de trabalho de agentes com eficiência em clusters do GKE, suspendendo agentes inativos e restaurando-os quando precisam agir novamente. O Agent Substrate é um software de código aberto que pode ser instalado em um cluster GKE Standard.

Este documento ajuda você a preparar seu projeto do Google Cloud e o cluster do GKE para o Agent Substrate, explica como executar o instalador e descreve os recursos que a instalação cria.

Preços

O Agent Substrate é oferecido sem custo financeiro extra no GKE. Os preços do GKE são aplicados aos recursos que você cria.

Limitações

O Agent Substrate tem as seguintes limitações de instalação:

  • Cloud Shell: não é possível instalar o Agent Substrate no Cloud Shell porque ele oferece 5 GB de armazenamento em disco permanente, o que é insuficiente para a instalação. Você precisa executar o instalador na sua máquina local.
  • Modo de cluster: é possível instalar o Agent Substrate apenas em clusters do GKE Standard. Os clusters do Autopilot não são compatíveis.
  • Clusters atuais e APIs Beta: se você ativar as APIs Beta necessárias (podcertificaterequests e clustertrustbundles) em um cluster atual que executa a versão 1.36, substitua os nós atuais antes de instalar o Agent Substrate. Os nós criados antes da atualização não têm a projeção de certificado do pod ativada (MountVolume.SetUp failed: unimplemented). Em clusters que executam a versão 1.37 ou mais recente, não é necessário substituir os nós atuais.
  • Tipos de máquina: não é possível usar séries de máquinas que executam arquiteturas de CPU mistas (como tipos de máquina E2).

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

  • Ative a API Google Kubernetes Engine.
    • Ativar a API Google Kubernetes Engine
  • Se você quiser usar a Google Cloud CLI para essa tarefa, instale e, em seguida, inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando o comando gcloud components update. Talvez as versões anteriores da CLI gcloud não sejam compatíveis com a execução dos comandos neste documento.
  • Instale os seguintes componentes na CLI gcloud:
    • kubectl
    • gke-gcloud-auth-plugin
  • Verifique se as seguintes ferramentas estão instaladas na sua máquina local:
    • Git para clonar o repositório Agent Substrate.
    • Go para executar os programas do instalador, que são distribuídos como código-fonte.
    • make para iniciar o instalador.

  • Como o instalador age em seu nome para ativar APIs e provisionar recursos, configure o Application Default Credentials (ADC) executando o comando abaixo:

    gcloud auth application-default login

    Para mais informações sobre a autenticação com o ADC, consulte Configurar o Application Default Credentials.

Funções exigidas

Para receber as permissões necessárias para instalar o Agent Substrate, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Requisitos de cluster

Se você permitir que o instalador crie um cluster, ele vai configurar automaticamente um cluster que atenda a todos os requisitos do Agent Substrate.

Se você preferir instalar o Agent Substrate em um cluster existente, ele precisará atender aos seguintes requisitos:

  • Executado no GKE Standard (o Agent Substrate é compatível apenas com clusters Standard).
  • Executa o GKE versão 1.36 (com flags Beta ativadas) ou versão 1.37 ou posterior.
  • Usa c3-standard-4 ou tipos de máquinas maiores para nós.

  • As APIs Kubernetes PodCertificateRequest e ClusterTrustBundle estão ativadas (certificates.k8s.io/v1beta1/podcertificaterequests e certificates.k8s.io/v1beta1/clustertrustbundles). Para ativar essas APIs em um cluster atual, execute o seguinte comando:

    gcloud container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-kubernetes-unstable-apis=certificates.k8s.io/v1beta1/podcertificaterequests,certificates.k8s.io/v1beta1/clustertrustbundles
    • Versão 1.36: depois de ativar as APIs, é necessário substituir os nós atuais, por exemplo, fazendo upgrade do pool de nós ou recriando os nós dele. A projeção de certificado do pod não está ativada em nós que existiam antes da atualização (MountVolume.SetUp failed: unimplemented).
    • Versão 1.37 ou mais recente: a projeção de certificado do pod já está ativada nos nós atuais. Portanto, não é necessário substituir os nós depois de ativar as APIs.

Instalar o Agent Substrate

Para instalar o Agent Substrate, execute o comando a seguir no terminal local:

curl -sSL https://raw.githubusercontent.com/ai-on-gke/substrate-gke/main/install.sh | bash

O instalador interativo solicita as configurações de projeto, cluster e armazenamento. Ele sugere padrões recomendados sempre que possível, que você pode aceitar ou personalizar:

  • ID do projeto (obrigatório): especifique o projeto Google Cloud em que os recursos serão provisionados. Se você configurou um projeto padrão para a CLI gcloud, o instalador usa esse ID do projeto.
  • Cluster (obrigatório): escolha se quer que o instalador crie um novo cluster do GKE com padrões recomendados ou instale o Agent Substrate em um cluster atual. Se você optar por instalar em um cluster atual, verifique se ele atende aos requisitos na seção Requisitos do cluster.
  • Bucket de snapshot (opcional): especifique um nome de bucket personalizado do Cloud Storage ou deixe em branco para que o instalador crie um bucket padrão chamado ate-snapshots-<project>-<zone>.

Quando for solicitado a selecionar uma origem de imagem do contêiner, escolha entre as seguintes opções:

  • Imagens pré-criadas: extrai imagens publicadas de um registro de contêiner. Como nada é criado ou enviado, seu projeto Google Cloud não precisa de um registro de contêiner próprio.
  • Build from source: cria as imagens do repositório Agent Substrate upstream (ou uma ramificação personalizada) e as envia para o registro do Artifact Registry do projeto.

O que o instalador faz

O instalador executa os seguintes programas em seu nome:

  • setup-gcp: cria ou verifica os recursos Google Cloud necessários, ativa APIs, cria o cluster do GKE (se você não escolheu usar um cluster atual) e o bucket do Cloud Storage e configura políticas do IAM.
  • ate-setup: implanta as imagens de contêiner e os controladores do Agent Substrate pré-criados no cluster do GKE.

Primeiro, o instalador faz as seguintes mudanças no projeto Google Cloud :

  1. Ativa as APIs Google Cloud necessárias para o Agent Substrate.
  2. Cria um cluster do GKE Standard (se não estiver usando um cluster atual) com as seguintes configurações:
    • Federação de Identidade da Carga de Trabalho para GKE: permite que o Agent Substrate acesse o Cloud Storage sem armazenar chaves nos nós.
    • GKE Dataplane V2: processa a rede necessária para rotear solicitações recebidas aos seus agentes.
    • APIs de certificado (PodCertificateRequest e ClusterTrustBundle): permite que essas APIs Beta do Kubernetes emitam certificados para comunicação TLS entre componentes do Agent Substrate.
    • OpenTelemetry gerenciado: coleta métricas e traces do seu cluster.
  3. Cria o bucket do Cloud Storage em que o Agent Substrate grava seus snapshots.
  4. Concede ao Agent Substrate acesso ao Cloud Storage para armazenar snapshots. Se você escolher criar da origem, também conceda acesso ao Artifact Registry para imagens de contêiner.
  5. Cria painéis do Cloud Monitoring que mostram a latência de roteamento, o tamanho do snapshot e o tráfego gRPC do Agent Substrate.

Em seguida, o instalador faz as seguintes mudanças no cluster:

  1. Adiciona o grupo de APIs e recursos do Agent Substrate ao seu cluster. Esses são recursos personalizados do Kubernetes, como ActorTemplate (que define as imagens e os recursos de contêiner usados pelos seus agentes) e WorkerPool (que define quantas caixas de areia inativas são mantidas prontas).
  2. Configura as autoridades certificadoras que emitem os certificados que identificam os componentes do Agent Substrate e seus atores. Os componentes apresentam esses certificados para se autenticarem usando mTLS.
  3. Implanta os componentes do Agent Substrate no cluster, junto com um banco de dados PostgreSQL que rastreia o estado dos atores e workers. O instalador aguarda até que o banco de dados e todos os pods do plano de controle estejam prontos.

O Agent Substrate implanta os componentes como cargas de trabalho comuns nos namespaces ate-system e podcertificate-controller-system. A instalação não modifica o plano de controle do GKE.

Os componentes implantados incluem o ambiente de execução baseado em gVisor que o Agent Substrate usa por padrão para isolar cada um dos seus agentes do nó em que ele é executado. O instalador não configura tempos de execução de microVMs. Para usar os tempos de execução de microVMs, é necessário implantá-los manualmente em um pool de nós com a virtualização aninhada ativada. Para mais detalhes, consulte as instruções de tempo de execução da microVM no repositório upstream do Agent Substrate.

Se a instalação falhar em algum momento (por exemplo, devido a um erro de rede transitório ou expiração do token), execute o comando novamente. O instalador preserva os recursos existentes e retoma de onde parou.

Para fazer upgrade do Agent Substrate em um cluster atual, execute o instalador e selecione Fazer upgrade de um cluster instalado. Para mais detalhes, consulte Fazer upgrade de um cluster instalado no README do substrate-gke.

Etapas opcionais

Depois de implantar os componentes principais, o instalador oferece as seguintes etapas opcionais:

  • Driver CSI do Filestore: instala o driver CSI do Filestore configurado para o Agent Substrate. Escolha essa opção se os agentes precisarem de armazenamento de arquivos compartilhados em pods, como espaços de trabalho ou repositórios compartilhados. Se o cluster tiver o complemento gerenciado do GKE Filestore ativado, o instalador o desativará antes de fazer o implante do driver.
  • Escalonamento automático do pool de nós: ativa o escalonamento automático de cluster do GKE no pool de nós. Você especifica o número mínimo e máximo de nós para o pool. Escolha essa opção se quiser que o GKE adicione nós automaticamente durante picos de demanda e remova nós quando os agentes forem suspensos. Pule essa opção se preferir uma contagem de nós fixa com custos de computação previsíveis.
  • Demonstração do contador: implanta uma carga de trabalho de exemplo que demonstra a suspensão e a restauração do agente. Escolha essa opção se quiser testar o cluster após a instalação. Para mais detalhes, consulte Teste a demonstração do contador.

Verifique a instalação

Para verificar se a instalação foi bem-sucedida e se os componentes principais estão em execução, execute os seguintes comandos e verifique se todos os pods têm o status Running:

kubectl get pods -n ate-system
kubectl get pods -n podcertificate-controller-system

Rotulagem e versões de nós

O instalador aplica o rótulo ate.dev/substrate-version a todos os nós do cluster. Esse rótulo especifica qual versão do Agent Substrate está instalada no cluster, e o Agent Substrate executa workers apenas em nós que têm esse rótulo de versão.

Para verificar qual versão do Agent Substrate está instalada no seu cluster, execute o seguinte comando:

kubectl get ds -n ate-system -l app=atelet -L ate.dev/substrate-version

Considere os seguintes detalhes de rotulagem de nós:

  • Pools de workers: ao criar um WorkerPool, configure-o para segmentar esta tag de versão. Para exemplos, consulte Fixar pools na versão instalada do substrato no guia da API Substrate.
  • Novos nós: o instalador rotula nós individuais, e não o pool de nós. Por isso, todos os novos nós adicionados após a instalação, mesmo em um pool de nós criado pelo instalador, começam sem o rótulo de versão. Você precisa rotular seu pool de nós do GKE para que os novos nós recebam automaticamente o rótulo.

Testar a demonstração do contador

Se você escolheu implantar a demonstração do contador quando solicitado pelo instalador, é possível observar os recursos de suspensão e restauração do Agent Substrate. A demonstração executa um pequeno servidor da Web que mantém uma contagem na memória.

Depois de implantar WorkerPool e ActorTemplate da demonstração, o instalador imprime os comandos necessários para criar um Actor com base no ActorTemplate e enviar uma solicitação para esse Actor. O README da demonstração do contador no repositório upstream do Agent Substrate explica as próximas etapas a serem seguidas.

Desinstalar o Agent Substrate

Quando a instalação for concluída e encerrada, o instalador vai imprimir comandos de limpeza personalizados para seu ambiente.

Para remover os recursos criados durante a instalação, escolha uma das seguintes opções:

  • Remover o Agent Substrate de um cluster atual: se você fez a instalação em um cluster atual e quer manter o cluster e as outras cargas de trabalho dele, exclua apenas os componentes do Agent Substrate executando o comando ate-setup delete ate-system que o instalador imprime. O instalador pré-preenche esse comando com os valores de projeto, cluster e local configurados durante a instalação.

  • Excluir todos os recursos (incluindo o cluster): para excluir o cluster do GKE, o bucket de snapshots, as vinculações do IAM e os painéis, execute o comando cleanup-gcp que o instalador imprime. O instalador pré-preenche esse comando com os valores de projeto, cluster, local e bucket configurados durante a instalação. Para mais detalhes, consulte a seção "Tearing down" do README do substrate-gke.

A seguir