Installa Agent Substrate su GKE

Agent Substrate su GKE esegue i workload degli agenti in modo efficiente sui cluster GKE: l'applicazione sospende gli agenti inattivi e il sistema li ripristina quando devono agire di nuovo. Agent Substrate su GKE è un software open source che puoi installare su un cluster GKE Standard. Per confrontare Agent Substrate su GKE con Agent Sandbox su GKE e scegliere un'architettura per i workload degli agenti AI, consulta Pianifica un'architettura per i workload degli agenti AI su GKE.

Questo documento ti aiuta a preparare il progetto Google Cloud e il cluster GKE per Agent Substrate su GKE, spiega come eseguire il programma di installazione e descrive le risorse create dall'installazione.

Prezzi

Agent Substrate su GKE è offerto senza costi aggiuntivi. I prezzi di GKE si applicano alle risorse che crei.

Limitazioni

Agent Substrate su GKE presenta le seguenti limitazioni di installazione:

  • Cloud Shell: non puoi installare Agent Substrate su GKE in Cloud Shell perché Cloud Shell fornisce 5 GB di spazio di archiviazione su disco permanente, che non è sufficiente per l'installazione. Devi eseguire il programma di installazione sulla tua macchina locale.
  • Modalità cluster: puoi installare Agent Substrate su GKE solo nei cluster GKE Standard. I cluster Autopilot non sono supportati.
  • Versione del cluster: sia il control plane che i node pool nel tuo cluster devono eseguire GKE 1.37 o versioni successive. Le versioni precedenti alla 1.37 non sono supportate.
  • Canale di rilascio: non puoi installare Agent Substrate su GKE nei cluster registrati nel canale di rilascio esteso. Il programma di installazione attiva le API beta di Kubernetes nel cluster e il canale Extended non supporta le API beta attivate esplicitamente.
  • Tipi di macchine: non puoi utilizzare serie di macchine eseguite su architetture della CPU miste (come i tipi di macchine E2).

Prima di iniziare

Prima di iniziare, assicurati di aver eseguito le seguenti attività:

  • Abilita l'API Google Kubernetes Engine.
    • Abilita l'API Google Kubernetes Engine
  • Per utilizzare Google Cloud CLI per questa attività, installala e poi inizializza gcloud CLI. Se hai già installato gcloud CLI, scarica l'ultima versione eseguendo il comando gcloud components update. Le versioni precedenti di gcloud CLI potrebbero non supportare l'esecuzione dei comandi in questo documento.
  • Installa i seguenti componenti in gcloud CLI:
    • kubectl
    • gke-gcloud-auth-plugin
  • Assicurati che i seguenti strumenti siano installati sulla tua macchina locale:
    • Git per clonare il repository Agent Substrate.
    • Go per eseguire i programmi del programma di installazione, che vengono distribuiti come codice sorgente.
    • make per avviare il programma di installazione.
    • Docker e il suo plug-in Buildx per creare le immagini container di Agent Substrate su GKE.
    • sha256sum, zstd, unzip e jq per configurare il runtime della microVM, se prevedi di utilizzarlo. Il programma di installazione non offre il runtime microVM se uno di questi strumenti non è presente.

  • Per consentire al programma di installazione di eseguire il push delle immagini che crea, configura Docker per l'autenticazione in Artifact Registry nella regione del tuo cluster:

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

    Sostituisci REGION con la regione del tuo cluster, ad esempio us-west1. Per saperne di più, consulta Configura l'autenticazione in Artifact Registry per Docker.

  • Poiché il programma di installazione agisce per tuo conto per abilitare le API ed eseguire il provisioning delle risorse, configura le Credenziali predefinite dell'applicazione (ADC) eseguendo il seguente comando:

    gcloud auth application-default login

    Per saperne di più sull'autenticazione con ADC, consulta Configura le credenziali predefinite dell'applicazione.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per installare Agent Substrate su GKE, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Requisiti per i cluster

Se consenti al programma di installazione di creare un cluster per te, questo configura automaticamente un cluster che soddisfa tutti i requisiti per Agent Substrate su GKE.

Se invece scegli di installare Agent Substrate su GKE in un cluster esistente, questo deve soddisfare i seguenti requisiti:

  • Viene eseguito su GKE Standard (Agent Substrate su GKE è supportato solo sui cluster Standard).
  • Esegue GKE versione 1.37 o successive sia sul control plane sia sui node pool. Se il control plane esegue una versione precedente, esegui prima l'upgrade del control plane. Quindi, esegui l'upgrade di tutti i node pool che eseguono una versione precedente in modo che i nodi possano montare i certificati dei pod nei pod.
  • Non è registrato nel canale di rilascio esteso. Per ulteriori informazioni, vedi Limitazioni.
  • Utilizza GKE Dataplane V2.
  • Utilizza tipi di macchine c3-standard-4 o più grandi per i nodi.

  • Se prevedi di eseguire più di circa 800 sandbox simultanee per nodo, il cluster utilizza nodi con limiti più elevati nel kernel Linux per il monitoraggio del file system (inotify) e per la tabella dei vicini del protocollo di risoluzione degli indirizzi (ARP). Senza questi limiti più elevati, le sandbox potrebbero non avviarsi e il networking potrebbe bloccarsi. I nodi richiedono le seguenti impostazioni del 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

    Il programma di installazione applica queste impostazioni automaticamente solo ai cluster che crea. Per applicare queste impostazioni ai node pool in un cluster esistente, utilizza una configurazione di sistema dei nodi. Per saperne di più, consulta Opzioni di configurazione di Sysctl.

Installa Agent Substrate su GKE

Per installare Agent Substrate su GKE, esegui uno dei seguenti comandi nel terminale locale:

  • Per l'installazione per i tuoi workload, esegui questo comando:

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

  • Per installare e poi provare la demo Counter, esegui il seguente comando:

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

Il programma di installazione interattivo ti chiede le immagini container e le impostazioni del progetto, del cluster, dello spazio di archiviazione e dell'ingress. Il programma di installazione suggerisce le impostazioni predefinite consigliate, ove possibile, che puoi accettare o personalizzare:

  • Immagini container (obbligatorio): quando il programma di installazione ti chiede di scegliere le immagini, seleziona Crea dall'origine. Il programma di installazione crea le immagini dal repository Agent Substrate upstream e ne esegue il push in un repository Artifact Registry nel tuo progetto. Per impostazione predefinita, il programma di installazione crea l'ultima versione di Agent Substrate. Per creare una versione diversa, inserisci un ramo, un tag o uno SHA di commit completo dal repository upstream.
  • ID progetto (obbligatorio): specifica il progetto Google Cloud in cui verrà eseguito il provisioning delle risorse. Se hai configurato un progetto predefinito per gcloud CLI, il programma di installazione utilizza l'ID progetto.
  • Cluster (obbligatorio): scegli se consentire al programma di installazione di creare un nuovo cluster GKE con i valori predefiniti consigliati o se installare Agent Substrate su GKE in un cluster esistente. Se scegli di eseguire l'installazione su un cluster esistente, verifica che soddisfi i requisiti nella sezione Requisiti del cluster.
  • Bucket snapshot (facoltativo): specifica un nome bucket Cloud Storage personalizzato o lascialo vuoto per consentire al programma di installazione di creare un bucket predefinito denominato ate-snapshots-<project>-<cluster>-<zone>. Poiché il nome predefinito include il nome del cluster, i cluster nello stesso progetto e nella stessa zona non condividono un bucket. Un nome personalizzato può contenere al massimo 56 caratteri, perché il programma di installazione crea anche un bucket di asset aggiungendo il suffisso -assets al nome e i nomi dei bucket possono contenere al massimo 63 caratteri. Se il nome predefinito è più lungo di 56 caratteri, il programma di installazione lo abbrevia e aggiunge un hash.
  • Client Ingress (obbligatorio): inserisci gli ID SPIFFE dei workload che inviano richieste agli attori, ad esempio il servizio di frontend o il servizio di backend della tua applicazione. Un ID SPIFFE identifica un workload in base allo spazio dei nomi e al account di servizio Kubernetes con cui vengono eseguiti i relativi pod. Ad esempio, i pod eseguiti nello spazio dei nomi shop come account di servizio frontend hanno l'ID SPIFFE spiffe://cluster.local/ns/shop/sa/frontend. Poiché l'ID dipende solo dallo spazio dei nomi e dal account di servizio, puoi inserire gli ID per i client di cui non hai ancora eseguito il deployment. Separa più ID con virgole. Le richieste raggiungono gli attori tramite un router in entrata, che ammette solo i client che presentano un certificato del pod il cui ID SPIFFE è presente in questo elenco. Qualsiasi client nell'elenco può raggiungere qualsiasi attore. Se includi il flag --demo, il programma di installazione consente solo i pod della demo Counter anziché richiedere gli ID. Per aggiungere client dopo l'installazione, consulta Reaching actors through the ingress router nel file README di substrate-gke.

Cosa fa il programma di installazione

Il programma di installazione esegue i seguenti programmi per tuo conto:

  • setup-gcp: crea o verifica le risorse Google Cloud richieste, abilita le API, crea il cluster GKE (se hai scelto di non utilizzare un cluster esistente) e il bucket Cloud Storage e configura i criteri IAM.
  • ate-setup: esegue il deployment delle immagini container e dei controller di Agent Substrate su GKE nel tuo cluster GKE.

Innanzitutto, il programma di installazione apporta le seguenti modifiche al tuo progetto Google Cloud :

  1. Abilita le API Google Cloud necessarie per Agent Substrate su GKE.
  2. Crea un cluster GKE Standard (se non utilizzi un cluster esistente) che esegue la versione 1.37 o successive e ha le seguenti impostazioni:
    • Workload Identity Federation for GKE: consente ad Agent Substrate su GKE di accedere a Cloud Storage senza archiviare le chiavi sui nodi.
    • GKE Dataplane V2: gestisce il networking necessario per instradare le richieste in entrata ai tuoi agenti.
    • OpenTelemetry gestito: raccoglie metriche e tracce dal tuo cluster.
  3. Crea i bucket Cloud Storage utilizzati da Agent Substrate su GKE: uno per gli snapshot e uno per i file necessari al runtime della microVM. Il nome del secondo bucket è il nome del bucket di snapshot seguito dal suffisso -assets.
  4. Crea un repository Artifact Registry denominato ate-images per le immagini container create dal programma di installazione.
  5. Crea un account di servizio denominato ate-snapshot-transfer che Agent Substrate su GKE utilizza per trasferire gli snapshot.
  6. Concede ai nodi GKE, ai componenti di Agent Substrate su GKE e al service account ate-snapshot-transfer le autorizzazioni IAM necessarie per accedere ai bucket e alle immagini container.
  7. Crea dashboard di Cloud Monitoring che tracciano la latenza di routing, le dimensioni degli snapshot e il traffico gRPC di Agent Substrate su GKE.

Successivamente, il programma di installazione apporta le seguenti modifiche al cluster:

  1. Aggiunge al cluster le risorse personalizzate di Kubernetes di Agent Substrate su GKE, come WorkerPool (che definisce il numero di sandbox inattive che rimangono pronte) e SandboxConfig (che definisce un runtime della sandbox). Altre risorse di Agent Substrate su GKE, come ActorTemplate (che definisce le immagini container e le risorse utilizzate dagli agenti) e gli attori, non sono risorse Kubernetes. Puoi gestirli tramite l'API Agent Substrate su GKE utilizzando il plug-in kubectl ate, un plug-in kubectl per la gestione di attori e worker. Per installare il plug-in, consulta Installa il plug-in kubectl ate.
  2. Configura le autorità di certificazione che emettono i certificati che identificano Agent Substrate sui componenti GKE e i tuoi attori. I componenti presentano questi certificati per autenticarsi tra loro utilizzando mTLS.
  3. Esegue il deployment dei componenti di Agent Substrate su GKE nel tuo cluster, insieme a un database PostgreSQL che monitora lo stato degli attori e dei worker. Il database archivia i propri dati su un disco permanente da 500 GiB. Il programma di installazione attende che il database e tutti i pod del control plane siano pronti. Per i cluster di produzione, puoi isolare il database PostgreSQL e i componenti dell'infrastruttura di sistema in node pool dedicati prima di eseguire il programma di installazione. Per istruzioni, consulta Isola l'infrastruttura di sistema e i pool di nodi worker.

Agent Substrate su GKE esegue il deployment dei suoi componenti come workload ordinari negli spazi dei nomi ate-system e podcertificate-controller-system. Se l'installazione avviene in un cluster esistente, il programma di installazione aggiorna anche il cluster per attivare le seguenti funzionalità, se sono disattivate: Workload Identity Federation for GKE, Managed OpenTelemetry e le versioni beta delle API Kubernetes podcertificaterequests e clustertrustbundles. L'attivazione delle API beta aggiorna il control plane di GKE, un'operazione che richiede circa 10 minuti.

I componenti di cui viene eseguito il deployment includono il runtime basato su gVisor utilizzato per impostazione predefinita da Agent Substrate su GKE per isolare ciascuno dei tuoi agenti dal nodo su cui viene eseguito. Se scegli il runtime microVM durante i passaggi facoltativi, il programma di installazione carica anche i file necessari per il runtime microVM su Cloud Storage e applica una risorsa SandboxConfig a livello di cluster denominata microvm che punta a questi file.

I worker che utilizzano il runtime microVM hanno bisogno di nodi che possano eseguire macchine virtuali. Quando il programma di installazione crea un cluster, il pool di nodi che crea ha la virtualizzazione nidificata abilitata. Se scegli la configurazione Avanzata e modifichi il tipo di macchina, scegli una serie di macchine che supporta la virtualizzazione nidificata, come C3, C4, N2 o N4.

Se installi Agent Substrate su GKE in un cluster esistente, il programma di installazione non aggiunge node pool al cluster. Per utilizzare il runtime microVM, il cluster deve avere un pool di nodi con la virtualizzazione nidificata abilitata o che utilizza un tipo di macchina bare metal x86. Puoi attivare la virtualizzazione nidificata solo quando crei un pool di nodi. Se il cluster non ha pool di nodi di questo tipo, il programma di installazione ti avvisa quando scegli il runtime microVM. Se continui, i worker microVM rimangono nello stato Pending. Per saperne di più su come configurare questi node pool, inclusi i taint, consulta Runtime di sandbox nel file README di substrate-gke.

Se l'installazione non va a buon fine in un qualsiasi momento (ad esempio a causa di un errore di rete temporaneo o della scadenza del token), esegui nuovamente il comando. Il programma di installazione conserva le risorse esistenti e riprende da dove aveva interrotto.

Per eseguire l'upgrade di un'installazione esistente di Agent Substrate su GKE, esegui il programma di installazione e seleziona Esegui l'upgrade di un cluster installato. Questa opzione non modifica il cluster. Il programma di installazione scarica invece il codice sorgente della versione installata e della versione di cui esegui l'upgrade e prepara la directory ~/ate-upgrade utilizzata dal runbook di upgrade. Per eseguire l'upgrade, esegui il comando stampato dal programma di installazione, quindi segui il runbook di upgrade nel repository Agent Substrate upstream del primo passaggio. Il runbook supporta gli upgrade a una release di patch successiva della stessa versione secondaria e, per la versione 1.0 e successive, alla versione secondaria successiva. Per le versioni precedenti alla 1.0, il passaggio a una versione secondaria successiva richiede una reinstallazione. Per maggiori dettagli, consulta Esegui l'upgrade di un cluster installato nel file README di substrate-gke.

Passaggi facoltativi

Dopo aver eseguito il deployment dei componenti principali, il programma di installazione offre i seguenti passaggi facoltativi:

  • Driver CSI Filestore: installa il driver CSI Filestore configurato per Agent Substrate su GKE. Scegli questa opzione se gli agenti hanno bisogno di uno spazio di archiviazione permanente che rimanga disponibile quando un agente riprende su un nodo diverso. Ogni agente ha il proprio spazio di archiviazione, che non è condiviso con altri agenti. L'assistenza in produzione per i volumi per agenti Filestore è in disponibilità generale limitata, quindi devi richiedere l'accesso. Per maggiori dettagli, vedi Utilizza i volumi per agenti di Filestore con Agent Substrate su GKE. Se nel cluster è abilitato il componente aggiuntivo Filestore GKE gestito, il programma di installazione lo disabilita prima di eseguire il deployment del driver. Il programma di installazione esegue il deployment del driver nello spazio dei nomi gcp-filestore-csi-driver e crea un service account denominato substrate-filestore-csi, che dispone delle autorizzazioni IAM necessarie per il driver.
  • Scalabilità automatica dei node pool: attiva la scalabilità automatica dei cluster GKE sul tuo pool di nodi. Specifica il numero minimo e massimo di nodi per il pool. Scegli questa opzione se vuoi che GKE aggiunga automaticamente nodi durante i picchi di domanda e li rimuova quando gli agenti vengono sospesi. Salta questa opzione se preferisci un numero di nodi fisso con costi di computing prevedibili. Per configurare il fallback automatico dell'hardware con ComputeClass personalizzate, buffer di capacità in standby e protezioni per lo scale down per gli attori attivi, consulta Progetta l'infrastruttura per Agent Substrate su GKE.
  • Runtime sandbox: consente di scegliere il runtime che isola gli agenti. Il programma di installazione installa il runtime gVisor come parte dei componenti principali, quindi il runtime gVisor non richiede alcuna configurazione aggiuntiva. Se vuoi un isolamento che utilizzi la virtualizzazione hardware, scegli il runtime microVM. Prima di scegliere questa opzione per un cluster esistente, assicurati che il cluster abbia un pool di nodi con la virtualizzazione nidificata abilitata o che utilizzi un tipo di macchina bare metal x86. Per maggiori dettagli, vedi Cosa fa il programma di installazione.
  • Demo del contatore: esegue il deployment di un workload di esempio che mostra la sospensione e il ripristino dell'agente. Questo passaggio viene visualizzato solo se includi il flag --demo quando avvii il programma di installazione. Scegli questa opzione se vuoi testare il cluster dopo l'installazione. Per maggiori dettagli, consulta Prova la demo del contatore.

Verifica l'installazione

Per verificare che l'installazione sia andata a buon fine e che i componenti principali siano in esecuzione, esegui i seguenti comandi e assicurati che tutti i pod abbiano lo stato Running:

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

Installa il plug-in kubectl ate

Per gestire gli attori e le risorse ActorTemplate, installa il plug-in kubectl ate dal codice sorgente della versione di Agent Substrate che hai installato:

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

Sostituisci VERSION con la versione di Agent Substrate che hai installato, ad esempio v1.0.0, la versione predefinita del programma di installazione.

Il comando go install inserisce il plug-in nella directory bin del tuo workspace Go. Lo strumento kubectl trova il plug-in solo se la directory si trova nella variabile di ambiente PATH. Se la variabile di ambiente PATH non include questa directory, aggiungila prima di eseguire qualsiasi comando kubectl ate:

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

Prova la demo del contatore

Se hai incluso il flag --demo quando hai eseguito il programma di installazione e hai scelto di eseguire il deployment della demo Counter, il programma di installazione esegue il deployment di un WorkerPool e di un ActorTemplate per un server web che conteggia le richieste in memoria e in un file. Agent Substrate su GKE conserva entrambi i conteggi quando sospendi e ripristini l'Actor che esegue il server.

Al termine dell'installazione, il programma di installazione stampa i passaggi successivi della demo: un comando che installa il plug-in kubectl ate e un comando che crea un attore da ActorTemplate. Prima di eseguire i comandi kubectl ate, assicurati che il plug-in si trovi nella variabile di ambiente PATH, come descritto in Installa il plug-in kubectl ate.

Il programma di installazione non stampa un comando che invia richieste all'attore. Il router in entrata ammette solo i client che presentano un certificato del pod il cui ID SPIFFE è incluso nella lista consentita, quindi rifiuta le richieste inviate direttamente dalla tua macchina locale. Per saperne di più sulla demo, consulta il file README della demo del contatore per la versione 1.0.0 di Agent Substrate, di cui il programma di installazione esegue il deployment per impostazione predefinita. In un cluster configurato dal programma di installazione, i passaggi del file README che inviano richieste tramite un port forwarding non funzionano per lo stesso motivo.

Disinstalla Agent Substrate su GKE

Al termine dell'installazione, il programma di installazione stampa i comandi di pulizia personalizzati per il tuo ambiente.

Per rimuovere le risorse create durante l'installazione, scegli una delle seguenti opzioni:

  • Rimuovi Agent Substrate su GKE da un cluster esistente: se hai eseguito l'installazione su un cluster esistente e vuoi conservare il cluster e gli altri workload, elimina solo i componenti di Agent Substrate su GKE eseguendo il comando ate-setup delete ate-system stampato dal programma di installazione. Il programma di installazione precompila questo comando con i valori di progetto, cluster e località configurati durante l'installazione.

  • Elimina tutte le risorse (incluso il cluster): per eliminare il cluster GKE, i bucket di snapshot e asset, il account di servizio ate-snapshot-transfer, le associazioni IAM, le dashboard e il repository Artifact Registry ate-images, esegui il comando cleanup-gcp stampato dal programma di installazione. Il programma di installazione precompila questo comando con i valori di progetto, cluster, località e bucket configurati durante l'installazione. Poiché il comando esegue lo script tools/cleanup-gcp utilizzando un percorso relativo, esegui il comando dalla directory in cui il programma di installazione ha clonato il repository substrate-gke. Per impostazione predefinita, il programma di installazione clona il repository nella directory ~/.substrate-gke.

    Se altri cluster nel progetto eseguono Agent Substrate su GKE, aggiungi il flag --cluster-scoped al comando. Questo flag mantiene le dashboard, il account di servizio ate-snapshot-transfer e le associazioni IAM a livello di progetto, che sono condivisi da questi cluster. Il flag --cluster-scoped non conserva il repository ate-images. Se altri cluster nella stessa regione utilizzano il repository ate-images, aggiungi anche il flag --keep-repository alla fine del comando. Per maggiori dettagli, consulta la sezione "Tearing down" del file README di substrate-gke.

Il comando cleanup-gcp non elimina le seguenti risorse:

  • Il disco permanente del database PostgreSQL: GKE conserva i Persistent Disk quando elimina un cluster, quindi continui a pagare per il disco da 500 GiB. Per eliminare il disco, esegui il comando ate-setup delete ate-system stampato dal programma di installazione. Quindi, attendi che il comando kubectl get pv non elenchi più un volume per la richiesta ate-system/data-postgres-0 prima di eseguire cleanup-gcp. Se hai già eliminato il cluster, trova il disco eseguendo il seguente comando, quindi eliminalo eseguendo il comando gcloud compute disks delete:

    gcloud compute disks list --filter="description~data-postgres-0"

  • Il service account substrate-filestore-csi: tutti i cluster del progetto che eseguono il driver CSI Filestore condividono questo service account. Se hai installato il driver e nessun altro cluster nel progetto lo esegue, elimina il account di servizio eseguendo questo comando:

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

    Sostituisci PROJECT_ID con l'ID progetto.

Passaggi successivi