Instalar o Agent Substrate no GKE

O Agent Substrate no GKE executa cargas de trabalho de agentes de forma eficiente em clusters do GKE: seu aplicativo suspende os agentes inativos, e o sistema os restaura quando eles precisam agir novamente. O Agent Substrate no GKE é um software de código aberto que pode ser instalado em um cluster do GKE Standard. Para comparar o Agent Substrate no GKE com o Agent Sandbox no GKE e escolher uma arquitetura para suas cargas de trabalho de agentes de IA, consulte Planejar uma arquitetura para cargas de trabalho de agentes de IA no GKE.

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

Preços

O Agent Substrate no GKE é oferecido sem custo financeiro adicional. Os preços do GKE se aplicam aos recursos que você cria.

Limitações

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

  • Cloud Shell: não é possível instalar o Agent Substrate no GKE no Cloud Shell porque o Cloud Shell oferece 5 GB de armazenamento em disco permanente, o que é insuficiente para a instalação. Execute o instalador na sua máquina local.
  • Modo de cluster: só é possível instalar o Agent Substrate no GKE em clusters do GKE Standard. Os clusters do Autopilot não são compatíveis.
  • Versão do cluster: o plano de controle e os pools de nós no cluster precisam executar o GKE versão 1.37 ou mais recente. As versões anteriores à 1.37 não são compatíveis.
  • Canal de lançamento: não é possível instalar o Agent Substrate no GKE em clusters registrados no canal de lançamento estendido. O instalador ativa as APIs Beta do Kubernetes no cluster, e o canal estendido não é compatível com APIs Beta ativadas explicitamente.
  • Tipos de máquina: não é possível usar séries de máquinas que são executadas em 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
  • Para usar a Google Cloud CLI nesta 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 máquina local:
    • Git para clonar o repositório do Agent Substrate.
    • Go para executar os programas do instalador, que são distribuídos como código-fonte.
    • make para iniciar o instalador.
    • Docker e o plug-in Buildx para criar o Agent Substrate nas imagens de contêiner do GKE.
    • sha256sum, zstd, unzip e jq para configurar o ambiente de execução da microVM, se você planeja usá-lo. O instalador não oferece o ambiente de execução da microVM se alguma dessas ferramentas estiver ausente.
  • Para permitir que o instalador envie as imagens criadas, configure o Docker para autenticar no Artifact Registry na região do cluster:

    gcloud auth configure-docker REGION-docker.pkg.dev
    

    Substitua REGION pela região do cluster, como us-west1. Para mais informações, consulte Configurar a autenticação no Artifact Registry para o Docker.

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

    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 no GKE, 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 para você, ele vai configurar automaticamente um cluster que atenda a todos os requisitos do Agent Substrate no GKE.

Se você optar por instalar o Agent Substrate no GKE em um cluster atual, ele precisará atender aos seguintes requisitos:

  • É executado no GKE Standard (o Agent Substrate no GKE é compatível apenas com clusters Standard).
  • Executa o GKE versão 1.37 ou posterior no plano de controle e nos pools de nós. Se o plano de controle executar uma versão anterior, faça upgrade do plano de controle primeiro. Em seguida, faça upgrade de todos os pools de nós que executam uma versão anterior para que os nós possam montar certificados de pod em pods.
  • Não está registrado no canal de lançamento estendido. Saiba mais em Limitações.
  • Usa o GKE Dataplane V2.
  • Usa tipos de máquina c3-standard-4 ou maiores para nós.
  • Se você planeja executar mais de aproximadamente 800 sandboxes simultâneos por nó, o cluster usa nós com limites mais altos no kernel do Linux para monitoramento do sistema de arquivos (inotify) e para a tabela vizinha do protocolo de resolução de endereço (ARP, na sigla em inglês). Sem esses limites mais altos, as sandboxes podem não ser iniciadas e a rede pode ser interrompida. Os nós precisam das seguintes configurações de kernel:

    • net.ipv4.neigh.default.gc_thresh1: 4096
    • net.ipv4.neigh.default.gc_thresh2: 16384
    • net.ipv4.neigh.default.gc_thresh3: 32768
    • fs.inotify.max_user_instances: 65536
    • fs.inotify.max_user_watches: 1048576

    O instalador aplica essas configurações automaticamente apenas aos clusters que ele cria. Para aplicar essas configurações a pools de nós em um cluster, use uma configuração do sistema de nós. Para mais informações, consulte Opções de configuração do sysctl.

Instalar o Agent Substrate no GKE

Para instalar o Agent Substrate no GKE, execute um dos seguintes comandos no terminal local:

  • Para instalar nas suas próprias cargas de trabalho, execute o seguinte comando:

    curl -sSL https://raw.githubusercontent.com/ai-on-gke/substrate-gke/main/install.sh | bash
    
  • Para instalar e testar a demonstração do contador, execute o seguinte comando:

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

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

  • Imagens do contêiner (obrigatório): quando o instalador pedir para você escolher as imagens, selecione Criar da origem. O instalador cria as imagens do repositório upstream do Agent Substrate e as envia para um repositório do Artifact Registry no seu projeto. Por padrão, o instalador cria a versão mais recente do Agent Substrate. Para criar uma versão diferente, insira uma ramificação, uma tag ou um SHA de confirmação completo do repositório upstream.
  • ID do projeto (obrigatório): especifique o projeto do Google Cloud em que os recursos serão provisionados. Se você configurou um projeto padrão para a CLI gcloud, o instalador usará esse ID do projeto.
  • Cluster (obrigatório): escolha se o instalador deve criar um novo cluster do GKE com os padrões recomendados ou instalar o Agent Substrate no GKE 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 personalizado para o bucket do Cloud Storage ou deixe em branco para que o instalador crie um bucket padrão chamado ate-snapshots-<project>-<cluster>-<zone>. Como o nome padrão inclui o nome do cluster, os clusters no mesmo projeto e zona não compartilham um bucket. Um nome personalizado pode ter no máximo 56 caracteres, porque o instalador também cria um bucket de recursos adicionando o sufixo -assets ao nome, e os nomes de buckets podem ter no máximo 63 caracteres. Se o nome padrão tiver mais de 56 caracteres, o instalador o encurtará e anexará um hash.
  • Clientes de entrada (obrigatório): insira os IDs SPIFFE das cargas de trabalho que enviam solicitações aos seus atores, como o serviço de front-end ou serviço de back-end do seu aplicativo. Um ID do SPIFFE identifica uma carga de trabalho pelo namespace e pela conta de serviço do Kubernetes em que os pods são executados. Por exemplo, os pods executados no namespace shop como a conta de serviço frontend têm o ID SPIFFE spiffe://cluster.local/ns/shop/sa/frontend. Como o ID depende apenas do namespace e da conta de serviço, é possível inserir IDs para clientes que você ainda não implantou. Separe vários IDs com vírgulas. As solicitações chegam aos atores por um roteador de entrada, que aceita apenas clientes que apresentam um certificado de pod com o ID SPIFFE nessa lista. Qualquer cliente na lista pode acessar qualquer ator. Se você incluir a flag --demo, o instalador vai permitir apenas os pods da demonstração do contador, em vez de solicitar IDs. Para adicionar clientes após a instalação, consulte Como alcançar atores pelo roteador de entrada no README do substrate-gke.

O que o instalador faz

O instalador executa os seguintes programas em seu nome:

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

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

  1. Ativa as APIs do Google Cloud necessárias para o Agent Substrate no GKE.
  2. Cria um cluster do GKE Standard (se não estiver usando um cluster atual) que executa a versão 1.37 ou posterior e tem as seguintes configurações:
    • Federação de Identidade da Carga de Trabalho para GKE: permite que o Agent Substrate no GKE acesse o Cloud Storage sem armazenar chaves nos nós.
    • GKE Dataplane V2: processa a rede necessária para rotear as solicitações recebidas para seus agentes.
    • OpenTelemetry gerenciado: coleta métricas e traces do cluster.
  3. Cria os buckets do Cloud Storage que o Agent Substrate no GKE usa: um para os snapshots e outro para os arquivos necessários para o ambiente de execução da microVM. O nome do segundo bucket é o nome do bucket de snapshot seguido pelo sufixo -assets.
  4. Cria um repositório do Artifact Registry chamado ate-images para as imagens do contêiner criadas pelo instalador.
  5. Cria uma conta de serviço chamada ate-snapshot-transfer que o Agent Substrate no GKE usa para transferir snapshots.
  6. Concede aos nós do GKE, aos componentes do Agent Substrate no GKE e à conta de serviço do ate-snapshot-transfer as permissões do IAM necessárias para acessar os buckets e as imagens de contêiner.
  7. 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 no GKE.

Em seguida, o instalador faz as seguintes alterações no cluster:

  1. Adiciona os recursos personalizados do Kubernetes do Agent Substrate no GKE ao cluster, como WorkerPool (que define quantos sandboxes inativos ficam prontos) e SandboxConfig (que define um ambiente de execução de sandbox). Outros recursos do Agent Substrate no GKE, como ActorTemplate (que define as imagens de contêiner e os recursos usados pelos agentes) e os atores, não são recursos do Kubernetes. Você os gerencia pela API Agent Substrate no GKE usando o plug-in kubectl ate, um plug-in kubectl para gerenciar atores e workers. Para instalar o plug-in, consulte Instalar o plug-in kubectl ate.
  2. Configura as autoridades certificadoras que emitem os certificados que identificam o Agent Substrate nos componentes do GKE e nos seus atores. Os componentes apresentam esses certificados para se autenticar uns aos outros usando mTLS.
  3. Implanta o Agent Substrate em componentes do GKE no seu cluster, além de um banco de dados PostgreSQL que rastreia o estado dos atores e workers. O banco de dados armazena os dados em um disco permanente de 500 GiB. O instalador aguarda até que o banco de dados e todos os pods do plano de controle fiquem prontos. Para clusters de produção, é possível isolar o banco de dados PostgreSQL e os componentes de infraestrutura do sistema em pools de nós dedicados antes de executar o instalador. Para instruções, consulte Isolar a infraestrutura do sistema e os pools de nós de trabalho.

O Agent Substrate no GKE implanta os componentes como cargas de trabalho comuns nos namespaces ate-system e podcertificate-controller-system. Se você instalar em um cluster atual, o instalador também vai atualizar o cluster para ativar os seguintes recursos, se estiverem desativados: Federação de Identidade da Carga de Trabalho para GKE, OpenTelemetry gerenciado e as versões Beta das APIs do Kubernetes podcertificaterequests e clustertrustbundles. A ativação das APIs Beta atualiza o plano de controle do GKE, o que leva cerca de 10 minutos.

Os componentes implantados incluem o ambiente de execução baseado em gVisor que o Agent Substrate no GKE usa por padrão para isolar cada um dos seus agentes do nó em que ele é executado. Se você escolher o ambiente de execução da microVM durante as etapas opcionais, o instalador também vai fazer upload dos arquivos necessários para o ambiente de execução da microVM para o Cloud Storage e aplicar um recurso SandboxConfig em todo o cluster chamado microvm que aponta para esses arquivos.

Os workers que usam o ambiente de execução de microVM precisam de nós que possam executar máquinas virtuais. Quando o instalador cria um cluster, o pool de nós criado tem a virtualização aninhada ativada. Se você escolher a configuração Avançada e alterar o tipo de máquina, escolha uma série de máquinas que ofereça suporte à virtualização aninhada, como C3, C4, N2 ou N4.

Se você instalar o Agent Substrate no GKE em um cluster existente, o instalador não vai adicionar pools de nós ao cluster. Para usar o ambiente de execução de microVM, o cluster precisa de um pool de nós com a virtualização aninhada ativada ou que use um tipo de máquina bare metal x86. Só é possível ativar a virtualização aninhada ao criar um pool de nós. Se o cluster não tiver esse pool de nós, o instalador vai avisar você quando você escolher o ambiente de execução da microVM. Se você continuar, os workers de microVM vão permanecer no estado Pending. Para mais informações sobre como configurar esses pools de nós, incluindo taints, consulte Ambientes de execução de sandbox no README do substrate-gke.

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

Para fazer upgrade de uma instalação do Agent Substrate no GKE, execute o instalador e selecione Fazer upgrade de um cluster instalado. Essa opção não altera o cluster. Em vez disso, o instalador faz o download do código-fonte da versão instalada e da versão para a qual você faz o upgrade e prepara o diretório ~/ate-upgrade que o runbook de upgrade usa. Para realizar o upgrade, execute o comando que o instalador mostra e, em seguida, siga o runbook de upgrade no repositório upstream do Agent Substrate da primeira etapa. O runbook é compatível com upgrades para uma versão de patch posterior da mesma versão secundária e, para a versão 1.0 e mais recentes, para a próxima versão secundária. Para versões anteriores à 1.0, é necessário reinstalar para mudar para uma versão secundária posterior. Para mais detalhes, consulte Como 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 no GKE. Escolha essa opção se os agentes precisarem de armazenamento permanente que permaneça disponível quando um agente for retomado em um nó diferente. Cada agente tem o próprio armazenamento, que não é compartilhado com outros agentes. O suporte Production para volumes do agente do Filestore é GA limitado, então você precisa solicitar acesso. Para mais detalhes, consulte Usar volumes do agente do Filestore com o Agent Substrate no GKE. Se o cluster tiver o complemento do Filestore do GKE gerenciado ativado, o instalador o desativará antes de implantar o driver. O instalador implanta o driver no namespace gcp-filestore-csi-driver e cria uma conta de serviço chamada substrate-filestore-csi, que tem as permissões do IAM necessárias para o driver.
  • Escalonamento automático do pool de nós: ativa o escalonamento automático de clusters do GKE no pool de nós. Especifique 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. Para configurar o fallback de hardware automatizado com ComputeClasses personalizadas, buffers de capacidade em espera e proteções de redução de escala vertical para agentes ativos, consulte Projetar sua infraestrutura para o Agent Substrate no GKE.
  • Ambiente de execução do sandbox: permite escolher o ambiente de execução que isola seus agentes. O instalador instala o ambiente de execução do gVisor como parte dos componentes principais, portanto, o ambiente de execução do gVisor não precisa de configuração extra. Se você quiser um isolamento que use a virtualização de hardware, escolha o ambiente de execução da microVM. Antes de escolher essa opção para um cluster atual, verifique se ele tem um pool de nós com a virtualização aninhada ativada ou que use um tipo de máquina bare metal x86. Para mais detalhes, consulte O que o instalador faz.
  • Demonstração do contador: implanta uma carga de trabalho de exemplo que demonstra a suspensão e a restauração do agente. Essa etapa só vai aparecer se você incluir a flag --demo ao iniciar o instalador. 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

Instalar o plug-in kubectl ate

Para gerenciar os recursos de atores e ActorTemplate, instale o plug-in kubectl ate do código-fonte da versão do Agent Substrate que você instalou:

git clone --depth 1 --branch VERSION https://github.com/agent-substrate/substrate.git
cd substrate
go install ./cmd/kubectl-ate

Substitua VERSION pela versão do Agent Substrate que você instalou, como v1.0.0, a versão padrão do instalador.

O comando go install coloca o plug-in no diretório bin do seu espaço de trabalho do Go. A ferramenta kubectl só vai encontrar o plug-in se esse diretório estiver na variável de ambiente PATH. Se a variável de ambiente PATH não incluir esse diretório, adicione-o antes de executar qualquer comando kubectl ate:

export PATH="$PATH:$(go env GOPATH)/bin"

Teste a demonstração do contador

Se você incluiu a flag --demo ao executar o instalador e optou por implantar a demonstração do contador, o instalador implanta um WorkerPool e um ActorTemplate para um servidor da Web que conta as solicitações na memória e em um arquivo. O Agent Substrate no GKE preserva as duas contagens quando você suspende e restaura o ator que executa o servidor.

Após a instalação, o instalador mostra as próximas etapas da demonstração: um comando que instala o plug-in kubectl ate e um comando que cria um ator do ActorTemplate. Antes de executar os comandos kubectl ate, verifique se o plug-in está na variável de ambiente PATH, conforme descrito em Instalar o plug-in kubectl ate.

O instalador não mostra um comando que envia solicitações ao ator. O roteador de entrada aceita apenas clientes que apresentam um certificado de pod com o ID SPIFFE na lista de permissões. Portanto, ele recusa solicitações enviadas diretamente da sua máquina local. Para mais informações sobre a demonstração, consulte o README da demonstração do contador para a versão 1.0.0 do Agent Substrate, que o instalador implanta por padrão. Em um cluster configurado pelo instalador, as etapas do README que enviam solicitações por um encaminhamento de porta não funcionam pelo mesmo motivo.

Desinstalar o Agent Substrate no GKE

Quando a instalação é concluída e encerrada, o instalador imprime 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 no GKE de um cluster atual: se você instalou em um cluster atual e quer manter o cluster e as outras cargas de trabalho dele, exclua apenas os componentes do Agent Substrate no GKE executando o comando ate-setup delete ate-system que o instalador mostra. 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, os buckets de snapshot e de recursos, a conta de serviço ate-snapshot-transfer, as vinculações do IAM, os painéis e o repositório do Artifact Registry ate-images, 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. Como o comando executa o script tools/cleanup-gcp usando um caminho relativo, execute o comando no diretório em que o instalador clonou o repositório substrate-gke. Por padrão, o instalador clona o repositório no diretório ~/.substrate-gke.

    Se outros clusters no projeto executarem o Agent Substrate no GKE, adicione a flag --cluster-scoped ao comando. Essa flag mantém os painéis, a conta de serviço ate-snapshot-transfer e as vinculações do IAM para envolvidos no projeto, que são compartilhadas por esses clusters. A flag --cluster-scoped não mantém o repositório ate-images. Se outros clusters na mesma região usarem o repositório ate-images, adicione também a sinalização --keep-repository ao final do comando. Para mais detalhes, consulte a seção "Como desativar" do README do substrate-gke.

O comando cleanup-gcp não exclui os seguintes recursos:

  • O disco permanente do banco de dados PostgreSQL: o GKE mantém os discos permanentes quando exclui um cluster. Portanto, você continua pagando pelo disco de 500 GiB. Para excluir o disco, execute o comando ate-setup delete ate-system que o instalador mostra. Em seguida, aguarde até que o comando kubectl get pv não liste mais um volume para a reivindicação ate-system/data-postgres-0 antes de executar cleanup-gcp. Se você já excluiu o cluster, encontre o disco executando o seguinte comando e, em seguida, exclua o disco executando o comando gcloud compute disks delete:

    gcloud compute disks list --filter="description~data-postgres-0"
    
  • A conta de serviço substrate-filestore-csi: todos os clusters no projeto que executam o driver CSI do Filestore compartilham essa conta de serviço. Se você instalou o driver e nenhum outro cluster no projeto executa o driver, exclua a conta de serviço executando o seguinte comando:

    gcloud iam service-accounts delete substrate-filestore-csi@PROJECT_ID.iam.gserviceaccount.com
    

    Substitua PROJECT_ID pelo ID do projeto.

A seguir