Installer Agent Substrate sur GKE

Agent Substrate on GKE exécute efficacement les charges de travail agentives sur les clusters GKE en suspendant les agents inactifs et en les restaurant lorsqu'ils doivent agir à nouveau. Agent Substrate on GKE est un logiciel Open Source que vous pouvez installer sur un cluster GKE Standard.

Ce document vous aide à préparer votre Google Cloud projet et votre cluster GKE pour Agent Substrate on GKE, explique comment exécuter le programme d'installation et décrit les ressources créées par l'installation.

Tarifs

Agent Substrate on GKE est proposé sans frais supplémentaires. Les tarifs GKE s'appliquent aux ressources que vous créez.

Limites

L'installation d'Agent Substrate on GKE présente les limites suivantes :

  • Cloud Shell : vous ne pouvez pas installer Agent Substrate on GKE dans Cloud Shell, car Cloud Shell fournit 5 Go d'espace de stockage sur disque persistant, ce qui est insuffisant pour l' installation. Vous devez exécuter le programme d'installation sur votre machine locale.
  • Mode de cluster : vous ne pouvez installer Agent Substrate on GKE que dans les clusters GKE Standard. Les clusters Autopilot ne sont pas compatibles.
  • Clusters existants et API bêta : si vous activez les API bêta requises (podcertificaterequests et clustertrustbundles) sur un cluster existant exécutant la version 1.36, vous devez remplacer les nœuds existants avant d'installer Agent Substrate on GKE. La projection de certificat de pod n'est pas activée sur les nœuds créés avant la mise à jour (MountVolume.SetUp failed: unimplemented). Sur les clusters exécutant la version 1.37 ou ultérieure, il n'est pas nécessaire de remplacer les nœuds existants.
  • Types de machines : vous ne pouvez pas utiliser de séries de machines exécutées sur des architectures de processeur mixtes (telles que les types de machines E2).

Avant de commencer

Avant de commencer, effectuez les tâches suivantes :

  • Activez l'API Google Kubernetes Engine.
    • Activer l'API Google Kubernetes Engine
  • Si vous souhaitez utiliser Google Cloud CLI pour cette tâche, installez puis initialisez la gcloud CLI. Si vous avez déjà installé la gcloud CLI, obtenez la dernière version en exécutant la gcloud components update commande. Il est possible que les versions antérieures de la gcloud CLI ne permettent pas d'exécuter les commandes de ce document.
  • Installez les composants suivants dans la gcloud CLI :
    • kubectl
    • gke-gcloud-auth-plugin
  • Assurez-vous que les outils suivants sont installés sur votre machine locale :
    • Git pour cloner le dépôt Agent Substrate.
    • Aller pour exécuter les programmes du programme d'installation, qui sont distribués sous forme de code source.
    • make pour démarrer le programme d'installation.

  • Étant donné que le programme d'installation agit en votre nom pour activer les API et provisionner les ressources, configurez les identifiants par défaut de l'application (ADC) en exécutant la commande suivante :

    gcloud auth application-default login

    Pour en savoir plus sur l'authentification avec les ADC, consultez Configurer les identifiants par défaut de l'application.

Rôles requis

Pour obtenir les autorisations nécessaires pour installer Agent Substrate on GKE, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

Configuration requise pour les clusters

Si vous laissez le programme d'installation créer un cluster pour vous, il configure automatiquement un cluster qui répond à toutes les exigences d'Agent Substrate on GKE.

Si vous choisissez d'installer Agent Substrate on GKE dans un cluster existant, celui-ci doit répondre aux exigences suivantes :

  • S'exécute sur GKE Standard (Agent Substrate on GKE n'est compatible qu'avec les clusters Standard).
  • Exécute GKE version 1.36 (avec les indicateurs bêta activés) ou version 1.37 ou ultérieure.
  • Utilise des types de machines c3-standard-4 ou plus grands pour les nœuds.

  • Les API Kubernetes PodCertificateRequest et ClusterTrustBundle sont activées (certificates.k8s.io/v1beta1/podcertificaterequests et certificates.k8s.io/v1beta1/clustertrustbundles). Pour activer ces API sur un cluster existant, exécutez la commande suivante :

    gcloud container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-kubernetes-unstable-apis=certificates.k8s.io/v1beta1/podcertificaterequests,certificates.k8s.io/v1beta1/clustertrustbundles
    • Version 1.36 : après avoir activé les API, vous devez remplacer les nœuds existants, par exemple en mettant à niveau le pool de nœuds ou en recréant ses nœuds. La projection de certificat de pod n'est pas activée sur les nœuds qui existaient avant la mise à jour (MountVolume.SetUp failed: unimplemented).
    • Version 1.37 ou ultérieure : la projection de certificat de pod est déjà activée sur les nœuds existants. Vous n'avez donc pas besoin de remplacer les nœuds après avoir activé les API.

Installer Agent Substrate on GKE

Pour installer Agent Substrate on GKE, exécutez la commande suivante dans votre terminal local :

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

Le programme d'installation interactif vous invite à saisir les paramètres de votre projet, de votre cluster et de votre espace de stockage. Il suggère des valeurs par défaut recommandées lorsque cela est possible, que vous pouvez accepter ou personnaliser :

  • ID du projet (obligatoire) : spécifiez le Google Cloud projet dans lequel les ressources seront provisionnées. Si vous avez configuré un projet par défaut pour la gcloud CLI, le programme d'installation utilise cet ID de projet.
  • Cluster (obligatoire) : choisissez de laisser le programme d'installation créer un cluster GKE avec les valeurs par défaut recommandées ou d'installer Agent Substrate on GKE dans un cluster existant. Si vous choisissez d'installer sur un cluster existant, vérifiez qu'il répond aux exigences de la section Configuration requise pour les clusters.
  • Bucket d'instantanés (facultatif) : spécifiez un nom de bucket Cloud Storage personnalisé ou laissez le champ vide pour que le programme d'installation crée un bucket par défaut nommé ate-snapshots-<project>-<zone>.

Lorsque vous êtes invité à sélectionner une source d'image de conteneur, vous pouvez choisir parmi les options suivantes :

  • Images prédéfinies : extrait les images publiées d'un registre de conteneurs. Comme rien n'est créé ni transféré, votre Google Cloud projet n'a pas besoin de son propre registre de conteneurs.
  • Créer à partir de la source : crée les images à partir du dépôt Agent Substrate en amont (ou d'une branche personnalisée) et les transfère vers le registre Artifact Registry de votre projet.

Fonction du programme d'installation

Le programme d'installation exécute les programmes suivants en votre nom :

  • setup-gcp : crée ou vérifie les ressources requises Google Cloud , active les API, crée le cluster GKE (si vous avez choisi de ne pas utiliser de cluster existant) et le bucket Cloud Storage, et configure les stratégies IAM.
  • ate-setup: déploie les images de conteneur et les contrôleurs Agent Substrate on GKE prédéfinis sur votre cluster GKE.

Tout d'abord, le programme d'installation apporte les modifications suivantes à votre Google Cloud projet :

  1. Active les Google Cloud API dont Agent Substrate on GKE a besoin.
  2. Crée un cluster GKE Standard (si vous n'utilisez pas de cluster existant) avec les paramètres suivants :
    • Fédération d'identité de charge de travail pour GKE : permet à Agent Substrate on GKE d'accéder à Cloud Storage sans stocker de clés sur les nœuds.
    • GKE Dataplane V2 : gère la mise en réseau requise pour acheminer les requêtes entrantes vers vos agents.
    • API de certificat (PodCertificateRequest et ClusterTrustBundle) : active ces API bêta Kubernetes pour émettre des certificats pour la communication TLS entre les composants Agent Substrate on GKE.
    • OpenTelemetry géré : collecte les métriques et les traces de votre cluster.
  3. Crée le bucket Cloud Storage dans lequel Agent Substrate on GKE écrit vos instantanés.
  4. Accorde à Agent Substrate on GKE l'accès à Cloud Storage pour stocker les instantanés. Si vous choisissez de créer à partir de la source, il accorde également l'accès à Artifact Registry pour les images de conteneur.
  5. Crée des tableaux de bord Cloud Monitoring qui représentent la latence de routage, la taille des instantanés et le trafic gRPC d'Agent Substrate on GKE.

Ensuite, le programme d'installation apporte les modifications suivantes à votre cluster :

  1. Ajoute le groupe d'API et les ressources Agent Substrate on GKE à votre cluster. Il s'agit de ressources personnalisées Kubernetes, telles que ActorTemplate (qui définit les images de conteneur et les ressources utilisées par vos agents) et WorkerPool (qui définit le nombre d'environnements en bac à sable inactifs à conserver).
  2. Configure les autorités de certification qui émettent les certificats identifiant les composants Agent Substrate on GKE et vos acteurs. Les composants présentent ces certificats pour s'authentifier mutuellement à l'aide de mTLS.
  3. Déploie les composants Agent Substrate on GKE sur votre cluster, ainsi qu'une base de données PostgreSQL qui suit l'état de vos acteurs et de vos nœuds de calcul. Le programme d'installation attend que la base de données et tous les pods du plan de contrôle soient prêts.

Agent Substrate on GKE déploie ses composants en tant que charges de travail ordinaires dans les espaces de noms ate-system et podcertificate-controller-system. L'installation ne modifie pas le plan de contrôle GKE.

Les composants déployés incluent l'environnement d'exécution basé sur gVisor qu'Agent Substrate on GKE utilise par défaut pour isoler chacun de vos agents du nœud sur lequel il s'exécute. Le programme d'installation ne configure pas les environnements d'exécution microVM. Pour utiliser les environnements d'exécution microVM, vous devez les déployer manuellement sur un pool de nœuds sur lequel la virtualisation imbriquée est activée. Pour en savoir plus, consultez les instructions relatives à l'environnement d'exécution microVM dans le dépôt Agent Substrate en amont.

Si l'installation échoue à un moment donné (par exemple, en raison d'une erreur réseau temporaire ou d'une expiration de jeton), réexécutez la commande. Le programme d'installation conserve les ressources existantes et reprend là où il s'était arrêté.

Pour mettre à niveau Agent Substrate on GKE dans un cluster existant, exécutez le programme d'installation et sélectionnez Upgrade an installed cluster (Mettre à niveau un cluster installé). Pour en savoir plus, consultez Mettre à niveau un cluster installé dans le fichier README substrate-gke.

Étapes facultatives

Après avoir déployé les composants essentiels, le programme d'installation propose les étapes facultatives suivantes :

  • Pilote CSI Filestore : installe le pilote CSI Filestore configuré pour Agent Substrate on GKE. Choisissez cette option si vos agents ont besoin d'un espace de stockage de fichiers partagé entre les pods, tel que des espaces de travail ou des dépôts partagés. Si le module complémentaire GKE Filestore géré est activé sur votre cluster, le programme d'installation le désactive avant de déployer le pilote.
  • Autoscaling du pool de nœuds : active l'autoscaling du cluster GKE sur votre pool de nœuds. Vous spécifiez le nombre minimal et maximal de nœuds pour le pool. Choisissez cette option si vous souhaitez que GKE ajoute automatiquement des nœuds lors des pics de demande et supprime des nœuds lorsque les agents sont suspendus. Ignorez cette option si vous préférez un nombre de nœuds fixe avec des coûts de calcul prévisibles.
  • Démo du compteur : déploie un exemple de charge de travail qui illustre la suspension et la restauration d'un agent. Choisissez cette option si vous souhaitez tester le cluster après l'installation. Pour en savoir plus, consultez Essayer la démo du compteur.

Vérifier l'installation

Pour vérifier que l'installation a réussi et que les composants essentiels sont en cours d'exécution, exécutez les commandes suivantes et assurez-vous que tous les pods ont l'état Running :

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

Libellisation et versions des nœuds

Le programme d'installation applique le libellé ate.dev/substrate-version à chaque nœud de votre cluster. Ce libellé spécifie la version d'Agent Substrate on GKE installée sur votre cluster, et Agent Substrate on GKE n'exécute les nœuds de calcul que sur les nœuds portant ce libellé de version.

Pour vérifier la version d'Agent Substrate on GKE installée sur votre cluster, exécutez la commande suivante :

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

Tenez compte des détails suivants concernant la libellisation des nœuds :

  • Pools de nœuds de calcul : lorsque vous créez un WorkerPool, configurez-le pour cibler ce tag de version. Pour obtenir des exemples, consultez Épingler des pools à la version de substrate installée dans le guide de l'API Substrate.
  • Nouveaux nœuds : le programme d'installation libellise les nœuds individuels plutôt que le pool de nœuds. Par conséquent, tous les nouveaux nœuds ajoutés après l'installation, même dans un pool de nœuds créé par le programme d'installation, démarrent sans le libellé de version. Vous devez libelliser votre pool de nœuds GKE afin que les nouveaux nœuds reçoivent automatiquement le libellé.

Essayer la démo du compteur

Si vous avez choisi de déployer la démo du compteur lorsque le programme d'installation vous y a invité, vous pouvez observer les fonctionnalités de suspension et de restauration d'Agent Substrate on GKE. La démo exécute un petit serveur Web qui conserve un décompte en mémoire.

Après avoir déployé les WorkerPool et ActorTemplate de la démo, le programme d'installation affiche les commandes dont vous avez besoin pour créer un Actor à partir du ActorTemplate et pour envoyer une requête à ce Actor. Le fichier README de la démo du compteur dans le dépôt Agent Substrate en amont explique les étapes suivantes à suivre.

Désinstaller Agent Substrate on GKE

Une fois l'installation terminée et fermée, le programme d'installation affiche des commandes de nettoyage personnalisées pour votre environnement.

Pour supprimer les ressources créées lors de l'installation, choisissez l'une des options suivantes :

  • Supprimer Agent Substrate on GKE d'un cluster existant : si vous avez installé sur un cluster existant et que vous souhaitez conserver le cluster et ses autres charges de travail, supprimez uniquement les composants Agent Substrate on GKE en exécutant la ate-setup delete ate-system commande affichée par le programme d'installation. Le programme d'installation préremplit cette commande avec les valeurs de projet, de cluster et d'emplacement configurées lors de l'installation.

  • Supprimer toutes les ressources (y compris le cluster) : pour supprimer le cluster GKE, le bucket d'instantanés, les liaisons IAM et les tableaux de bord, exécutez la commande cleanup-gcp affichée par le programme d'installation. Le programme d'installation préremplit cette commande avec les valeurs de projet, de cluster, d'emplacement et de bucket configurées lors de l'installation. Pour en savoir plus, consultez la section "Tearing down" (Démantèlement) du fichier README substrate-gke.

Étape suivante