Installa Agent Substrate su GKE

Agent Substrate su GKE esegue in modo efficiente i workload agentici sui cluster GKE sospendendo gli agenti inattivi e ripristinandoli quando devono agire di nuovo. Agent Substrate su GKE è un software open source che puoi installare su un cluster GKE standard.

Questo documento ti aiuta a preparare il tuo Google Cloud progetto 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, insufficienti 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.
  • Cluster esistenti e API beta: se abiliti le API beta richieste (podcertificaterequests e clustertrustbundles) su un cluster esistente che esegue la versione 1.36, devi sostituire i nodi esistenti prima di installare Agent Substrate su GKE. I nodi creati prima dell'aggiornamento non hanno la proiezione del certificato del pod abilitata (MountVolume.SetUp failed: unimplemented). Nei cluster che eseguono la versione 1.37 o successive, non è necessario sostituire i nodi esistenti.
  • Tipi di macchine: non puoi utilizzare le 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 attività:

  • Abilita l'API Google Kubernetes Engine.
    • Abilita l'API Google Kubernetes Engine
  • Se vuoi 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 gcloud components update comando. 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.
    • Vai a eseguire i programmi del programma di installazione, che sono 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, 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 per il tuo 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, quest'ultimo deve soddisfare i seguenti requisiti:

  • Viene eseguito su GKE Standard (Agent Substrate su GKE è supportato solo sui cluster Standard).
  • Esegue GKE versione 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.

  • Le API Kubernetes PodCertificateRequest e ClusterTrustBundle sono abilitate (certificates.k8s.io/v1beta1/podcertificaterequests e certificates.k8s.io/v1beta1/clustertrustbundles). Per abilitare queste API su un cluster esistente, esegui il seguente 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
    • Versione 1.36: dopo aver abilitato le API, devi sostituire i nodi esistenti, ad esempio eseguendo l'upgrade del pool di nodi o ricreando i relativi nodi. La proiezione del certificato del pod non è abilitata sui nodi esistenti prima dell'aggiornamento (MountVolume.SetUp failed: unimplemented).
    • Versione 1.37 o successive: la proiezione del certificato del pod è già abilitata sui nodi esistenti, quindi non è necessario sostituire i nodi dopo aver abilitato le API.

Installa Agent Substrate su GKE

Per installare Agent Substrate su GKE, esegui il seguente 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. Se possibile, suggerisce le impostazioni predefinite consigliate, che puoi accettare o personalizzare:

  • ID progetto (obbligatorio): specifica il Google Cloud progetto in cui verrà 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 GKE in un cluster esistente. Se scegli di eseguire l'installazione su un cluster esistente, verifica che soddisfi i requisiti indicati nella sezione Requisiti per i cluster.
  • Bucket di 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 precompilate: estrae le immagini pubblicate da un Container Registry. Poiché non viene creata o eseguita il push di alcuna immagine, il tuo Google Cloud progetto non ha bisogno di un Container Registry.
  • Crea dal codice sorgente: crea le immagini dal repository upstream Agent Substrate (o da un ramo personalizzato) ed esegue il push nel 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 richieste Google Cloud 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 precompilati di Agent Substrate su GKE nel cluster GKE.

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

  1. Abilita le Google Cloud API necessarie per Agent Substrate su GKE.
  2. Crea un cluster GKE standard (se non utilizzi un cluster esistente) con le seguenti impostazioni:
    • Federazione di Workload Identity per GKE: consente ad Agent Substrate su GKE di accedere a Cloud Storage senza memorizzare le chiavi sui nodi.
    • GKE Dataplane V2: gestisce la rete necessaria per instradare le richieste in entrata agli agenti.
    • API dei certificati (PodCertificateRequest e ClusterTrustBundle): abilita queste API beta di Kubernetes per emettere certificati per la comunicazione TLS tra i componenti di Agent Substrate su GKE.
    • OpenTelemetry gestito: raccoglie metriche e tracce dal tuo cluster.
  3. Crea il bucket Cloud Storage in cui Agent Substrate su GKE scrive gli snapshot.
  4. Concede ad Agent Substrate su GKE 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 rappresentano graficamente 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 il gruppo di API e le risorse di Agent Substrate su GKE 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 da mantenere pronte).
  2. Configura le autorità di certificazione che emettono i certificati che identificano i componenti di Agent Substrate su GKE e gli attori. I componenti presentano questi certificati per autenticarsi a vicenda utilizzando mTLS.
  3. Esegue il deployment dei componenti di Agent Substrate su GKE nel cluster, insieme a un database PostgreSQL che tiene traccia dello stato degli attori e dei worker. Il programma di installazione attende che il database e tutti i pod del piano di controllo siano pronti.

Agent Substrate su GKE esegue il deployment dei suoi componenti come workload normali all'interno degli spazi dei nomi ate-system e podcertificate-controller-system. L'installazione non modifica il piano di controllo GKE.

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

Se l'installazione non riesce 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 si era interrotto.

Per eseguire l'upgrade di Agent Substrate su GKE in un cluster esistente, esegui il programma di installazione e seleziona Esegui l'upgrade di un cluster installato. Per maggiori dettagli, consulta la sezione Eseguire l'upgrade di un cluster installato nel file substrate-gke README.

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 file condiviso tra i pod, ad esempio workspace o repository condivisi. Se il cluster ha il componente aggiuntivo Filestore GKE 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 nel pool di nodi. Specifica il numero minimo e massimo di nodi per il pool. Scegli questa opzione se vuoi che GKE aggiunga automaticamente i 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 calcolo prevedibili.
  • Demo del contatore: esegue il deployment di un workload di esempio che mostra la sospensione e il ripristino degli agenti. 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

Etichettatura e versioni dei nodi

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

Per verificare la versione di Agent Substrate su GKE installata nel cluster, esegui il seguente comando:

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

Tieni presenti i seguenti dettagli sull'etichettatura dei nodi:

  • Pool di worker: quando crei un WorkerPool, configurarlo in modo che sia destinato a questo tag di versione. Per esempi, consulta la sezione Aggiungere i pool alla versione di substrate 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 di versione. Devi etichettare il tuo 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 del contatore quando ti è stato chiesto dal programma di installazione, puoi osservare le funzionalità di sospensione e ripristino di Agent Substrate su GKE. La demo esegue un piccolo server web che mantiene 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 questo Actor. Il file README della demo del contatore nel repository Agent Substrate upstream spiega i passaggi successivi da eseguire.

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 ate-setup delete ate-system comando 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 di snapshot, le associazioni IAM e le dashboard, 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. Per maggiori dettagli, consulta la sezione "Tearing down" del file README di substrate-gke.

Passaggi successivi