Installa Agent Substrate su GKE

Agent Substrate esegue in modo efficiente i carichi di lavoro degli agenti sui cluster GKE sospendendo gli agenti inattivi e ripristinandoli quando devono agire di nuovo. Agent Substrate è un software open source che puoi installare in un cluster GKE Standard.

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

Prezzi

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

Limitazioni

Agent Substrate presenta le seguenti limitazioni di installazione:

  • Cloud Shell: non puoi installare Agent Substrate in Cloud Shell perché Cloud Shell fornisce 5 GB di spazio di archiviazione su disco permanente, che non sono sufficienti per l'installazione. Devi eseguire il programma di installazione sulla tua macchina locale.
  • Modalità cluster: puoi installare Agent Substrate solo sui cluster GKE Standard. I cluster Autopilot non sono supportati.
  • Cluster esistenti e API beta: non puoi abilitare le API beta richieste (podcertificaterequests e clustertrustbundles) su un cluster esistente. Se esegui l'installazione su un cluster esistente che esegue la versione 1.36, queste API devono essere state abilitate al momento della creazione del cluster.
  • Tipi di macchine: non puoi utilizzare serie di macchine che vengono eseguite su architetture CPU miste (ad esempio i tipi di macchine E2).

Prima di iniziare

Prima di iniziare, assicurati di aver eseguito le seguenti operazioni:

  • Attiva l'API Google Kubernetes Engine.
    • Attiva 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 nella gcloud CLI:
    • kubectl
    • gke-gcloud-auth-plugin
  • Assicurati che sulla tua macchina locale siano installati i seguenti strumenti:
    • 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.

  • Poiché il programma di installazione agisce per tuo conto per abilitare le API e il provisioning delle risorse, configuraCredenziali predefinite dell'applicazionee (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, 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 lasci che il programma di installazione crei un cluster per te, configura automaticamente un cluster che soddisfi tutti i requisiti per Agent Substrate.

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

  • Viene eseguito su GKE Standard (Agent Substrate è supportato solo sui cluster Standard).
  • Esegue GKE 1.36 (con i flag beta abilitati) o versione 1.37 o successive.
  • Utilizza tipi di macchine c3-standard-4 o più grandi per i nodi.
  • Sono state abilitate le API Kubernetes PodCertificateRequest e ClusterTrustBundle (certificates.k8s.io/v1beta1/podcertificaterequests e certificates.k8s.io/v1beta1/clustertrustbundles). Queste API sono in disponibilità generale in Kubernetes versione 1.37 o successive, il che significa che sono abilitate su qualsiasi cluster che esegue la versione 1.37 o successive. Devi attivarli manualmente solo sui cluster esistenti che eseguono le versioni patch 1.36. Per istruzioni, vedi Attivare le API beta su un cluster esistente.

Installa Agent Substrate

Per installare Agent Substrate, esegui questo comando nel terminale locale:

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

Il programma di installazione interattivo ti chiede le impostazioni di progetto, cluster e spazio di archiviazione. Suggerisce i valori predefiniti consigliati, che puoi accettare o personalizzare:

  • ID progetto (obbligatorio): specifica il progetto Google Cloud in cui verranno eseguito il provisioning delle risorse. Se hai configurato un progetto predefinito per gcloud CLI, il programma di installazione utilizza questo ID progetto.
  • Cluster (obbligatorio): scegli se consentire al programma di installazione di creare un nuovo cluster GKE con le impostazioni predefinite consigliate o di installare Agent Substrate su 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 di bucket Cloud Storage personalizzato o lascialo vuoto per consentire al programma di installazione di creare un bucket predefinito denominato ate-snapshots-<project>-<zone>.

Quando ti viene chiesto di selezionare un'origine dell'immagine container, puoi scegliere tra le seguenti opzioni:

  • Immagini predefinite: esegue il pull delle immagini pubblicate da un container registry. Poiché non viene creato o inviato nulla, il tuo progetto Google Cloud non ha bisogno di un proprio registro dei container.
  • Build from source: crea le immagini dal repository Agent Substrate (o da un ramo personalizzato) e le invia al registro Artifact Registry del tuo progetto.

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 precompilati nel 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.
  2. Crea un cluster GKE Standard (se non utilizzi un cluster esistente) con le seguenti impostazioni:
    • Workload Identity Federation for GKE: consente ad Agent Substrate di accedere a Cloud Storage senza archiviare le chiavi sui nodi.
    • GKE Dataplane V2: gestisce il networking necessario per instradare le richieste in entrata agli agenti.
    • API Certificate (PodCertificateRequest e ClusterTrustBundle): consente a queste API Kubernetes beta di emettere certificati per la comunicazione TLS tra i componenti di Agent Substrate.
    • OpenTelemetry gestito: raccoglie metriche e tracce dal tuo cluster.
  3. Crea il bucket Cloud Storage in cui Agent Substrate scrive gli snapshot.
  4. Concede all'agente Substrate l'accesso a Cloud Storage per l'archiviazione degli snapshot. Se scegli di creare dal codice sorgente, concede anche l'accesso ad Artifact Registry per le immagini container.
  5. Crea dashboard Cloud Monitoring che tracciano la latenza di routing, le dimensioni degli snapshot e il traffico gRPC di Agent Substrate.

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

  1. Aggiunge il gruppo di API e le risorse di Agent Substrate al cluster. Si tratta di risorse personalizzate di Kubernetes, come ActorTemplate (che definisce le immagini container e le risorse utilizzate dagli agenti) e WorkerPool (che definisce il numero di sandbox inattive mantenute pronte).
  2. Configura le autorità di certificazione che emettono i certificati che identificano i componenti di Agent Substrate e i tuoi attori. I componenti presentano questi certificati per autenticarsi a vicenda utilizzando mTLS.
  3. Esegue il deployment dei componenti di Agent Substrate nel cluster, insieme a un database PostgreSQL che tiene traccia dello stato di attori e lavoratori. Il programma di installazione attende che il database e tutti i pod del control plane siano pronti.

Agent Substrate esegue il deployment dei suoi componenti come carichi di lavoro ordinari all'interno degli spazi dei nomi ate-system e podcertificate-controller-system. L'installazione non modifica il control plane GKE.

I componenti di cui viene eseguito il deployment includono il runtime basato su gVisor che Agent Substrate utilizza per impostazione predefinita per isolare ciascuno dei tuoi agenti dal nodo su cui viene eseguito. Il programma di installazione non configura i runtime microVM. Per utilizzare i runtime microVM, devi eseguirne il deployment manuale in un pool di nodi in cui è abilitata la virtualizzazione nidificata. Per maggiori dettagli, consulta le istruzioni di runtime di microVM nel repository Agent Substrate upstream.

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

Per eseguire l'upgrade di Agent Substrate su un cluster esistente, esegui il programma di installazione e seleziona Esegui l'upgrade di un cluster installato. Per maggiori dettagli, vedi Eseguire 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. Scegli questa opzione se gli agenti hanno bisogno di uno spazio di archiviazione condiviso tra i pod, ad esempio spazi di lavoro o repository condivisi. Se il cluster ha il componente aggiuntivo GKE Filestore gestito abilitato, il programma di installazione lo disabilita prima di eseguire il deployment del driver.
  • Scalabilità automatica del pool di nodi: abilita la scalabilità automatica dei cluster GKE sul tuo node pool. Specifichi 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 rimuova i nodi quando gli agenti vengono sospesi. Salta questa opzione se preferisci un numero fisso di nodi con costi di calcolo prevedibili.
  • Counter demo: esegue il deployment di un workload di esempio che mostra la sospensione e il ripristino dell'agente. Scegli questa opzione se vuoi testare il cluster dopo l'installazione. Per maggiori dettagli, vedi Prova la demo del contatore.

Verifica l'installazione

Per verificare che l'installazione sia riuscita 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

Etichettatura dei nodi e versioni

Il programma di installazione applica l'etichetta ate.dev/substrate-version a ogni nodo del cluster. Questa etichetta specifica la versione di Agent Substrate installata sul cluster e Agent Substrate esegue i worker solo sui nodi che hanno questa etichetta di versione.

Per controllare la versione di Agent Substrate installata sul cluster, esegui questo comando:

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

Considera i seguenti dettagli di etichettatura dei nodi:

  • Pool di worker: quando crei un WorkerPool, configuralo in modo che abbia come target questo tag di versione. Per esempi, vedi Bloccare i pool alla versione del substrato installata nella guida all'API Substrate.
  • Nuovi nodi: il programma di installazione etichetta i singoli nodi anziché il pool di nodi. Per questo motivo, tutti i nuovi nodi aggiunti dopo l'installazione, anche in un pool di nodi creato dal programma di installazione, iniziano senza l'etichetta della versione. Devi etichettare il pool di nodi GKE in modo che i nuovi nodi ricevano automaticamente l'etichetta.

Prova la demo del contatore

Se hai scelto di eseguire il deployment della demo Counter quando richiesto dal programma di installazione, puoi osservare le funzionalità di sospensione e ripristino di Agent Substrate. La demo esegue un piccolo server web che tiene un conteggio in memoria.

Dopo aver eseguito il deployment di WorkerPool e ActorTemplate della demo, il programma di installazione stampa i comandi necessari per creare un Actor da ActorTemplate e per inviare una richiesta a Actor. Il file README della demo del contatore nel repository Agent Substrate upstream spiega i passaggi successivi da seguire.

Disinstallare Agent Substrate

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

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

  • Rimuovi Agent Substrate 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 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, il bucket snapshot, i binding IAM e i dashboard, esegui il comando cleanup-gcp stampato dal programma di installazione. Il programma di installazione precompila questo comando con i valori di progetto, cluster, posizione e bucket configurati durante l'installazione. Per maggiori dettagli, consulta la sezione "Tearing down" del file README di substrate-gke.

Passaggi successivi