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:
kubectlgke-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.
makepara iniciar o instalador.- Docker e o plug-in Buildx para criar o Agent Substrate nas imagens de contêiner do GKE.
sha256sum,zstd,unzipejqpara 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.devSubstitua
REGIONpela região do cluster, comous-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 loginPara 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:
- Administrador do Service Usage (
roles/serviceusage.serviceUsageAdmin) - Administrador do Kubernetes Engine (
roles/container.admin) - Administrador de armazenamento (
roles/storage.admin) - Administrador do Artifact Registry (
roles/artifactregistry.admin) - Administrador de projetos do IAM (
roles/resourcemanager.projectIamAdmin) - Administrador da conta de serviço (
roles/iam.serviceAccountAdmin) - Editor de monitoramento (
roles/monitoring.editor)
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-4ou 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:4096net.ipv4.neigh.default.gc_thresh2:16384net.ipv4.neigh.default.gc_thresh3:32768fs.inotify.max_user_instances:65536fs.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 | bashPara 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-assetsao 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
shopcomo a conta de serviçofrontendtêm o ID SPIFFEspiffe://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 dosubstrate-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 :
- Ativa as APIs do Google Cloud necessárias para o Agent Substrate no GKE.
- 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.
- 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. - Cria um repositório do Artifact Registry chamado
ate-imagespara as imagens do contêiner criadas pelo instalador. - Cria uma conta de serviço chamada
ate-snapshot-transferque o Agent Substrate no GKE usa para transferir snapshots. - Concede aos nós do GKE, aos componentes do Agent Substrate no
GKE e à conta de serviço do
ate-snapshot-transferas permissões do IAM necessárias para acessar os buckets e as imagens de contêiner. - 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:
- Adiciona os recursos personalizados do Kubernetes do Agent Substrate no GKE
ao cluster, como
WorkerPool(que define quantos sandboxes inativos ficam prontos) eSandboxConfig(que define um ambiente de execução de sandbox). Outros recursos do Agent Substrate no GKE, comoActorTemplate(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-inkubectl ate, um plug-inkubectlpara gerenciar atores e workers. Para instalar o plug-in, consulte Instalar o plug-inkubectl ate. - 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.
- 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-drivere cria uma conta de serviço chamadasubstrate-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
--demoao 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-systemque 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 Registryate-images, execute o comandocleanup-gcpque 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 scripttools/cleanup-gcpusando um caminho relativo, execute o comando no diretório em que o instalador clonou o repositóriosubstrate-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-scopedao comando. Essa flag mantém os painéis, a conta de serviçoate-snapshot-transfere as vinculações do IAM para envolvidos no projeto, que são compartilhadas por esses clusters. A flag--cluster-scopednão mantém o repositórioate-images. Se outros clusters na mesma região usarem o repositórioate-images, adicione também a sinalização--keep-repositoryao 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-systemque o instalador mostra. Em seguida, aguarde até que o comandokubectl get pvnão liste mais um volume para a reivindicaçãoate-system/data-postgres-0antes de executarcleanup-gcp. Se você já excluiu o cluster, encontre o disco executando o seguinte comando e, em seguida, exclua o disco executando o comandogcloud 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.comSubstitua
PROJECT_IDpelo ID do projeto.
A seguir
- Para saber mais sobre o Agent Substrate no GKE, consulte Sobre o Agent Substrate no GKE.
- Para dimensionar o cluster para a escala de produção, isolar os pools de nós do sistema e configurar ComputeClasses personalizadas e buffers de capacidade, consulte Projetar sua infraestrutura para o Agent Substrate no GKE.