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 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 tipos de máquina c3-standard-4 ou 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 uma das 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 existente) 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 do código-fonte, 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 seus 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 vai desativá-lo antes de implantar o 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 essa 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.

Teste 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 do ActorTemplate e enviar uma solicitação a 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