Installer Agent Substrate sur GKE

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

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

Tarifs

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

Limites

Le sous-strat d'agent présente les limites d'installation suivantes :

  • Cloud Shell : vous ne pouvez pas installer Agent Substrate 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 cluster : vous ne pouvez installer Agent Substrate que sur les clusters GKE Standard. Les clusters Autopilot ne sont pas compatibles.
  • Clusters existants et API bêta : vous ne pouvez pas activer les API bêta requises (podcertificaterequests et clustertrustbundles) sur un cluster existant. Si vous effectuez l'installation sur un cluster existant exécutant la version 1.36, ces API doivent avoir été activées lors de la création du cluster.
  • Types de machines : vous ne pouvez pas utiliser les séries de machines qui s'exécutent sur des architectures de processeur mixtes (comme 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
  • Pour utiliser Google Cloud CLI pour cette tâche, installez puis initialisez gcloud CLI. Si vous avez déjà installé la gcloud CLI, obtenez la dernière version en exécutant la commande gcloud components update. 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.
    • Go 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 ADC, consultez Configurer les identifiants par défaut de l'application.

Rôles requis

Pour obtenir les autorisations nécessaires pour installer Agent Substrate, 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 avec 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 pour Agent Substrate.

Si vous choisissez d'installer Agent Substrate sur un cluster existant, ce cluster doit répondre aux exigences suivantes :

  • S'exécute sur GKE Standard (le sous-strat d'agent 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 pour les nœuds.
  • Les API Kubernetes PodCertificateRequest et ClusterTrustBundle sont activées (certificates.k8s.io/v1beta1/podcertificaterequests et certificates.k8s.io/v1beta1/clustertrustbundles). Ces API sont en disponibilité générale dans Kubernetes version 1.37 ou ultérieure, ce qui signifie qu'elles sont activées sur tous les clusters exécutant la version 1.37 ou ultérieure. Vous n'avez besoin de les activer manuellement que sur les clusters existants exécutant les versions de correctif 1.36. Pour obtenir des instructions, consultez Activer les API bêta sur un cluster existant.

Installer Agent Substrate

Pour installer Agent Substrate, 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 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 projet Google Cloud dans lequel les ressources seront provisionnées. Si vous avez configuré un projet par défaut pour gcloud CLI, le programme d'installation utilise cet ID de projet.
  • Cluster (obligatoire) : choisissez si vous souhaitez que le programme d'installation crée un cluster GKE avec les paramètres par défaut recommandés ou installe Agent Substrate sur un cluster existant. Si vous choisissez d'installer sur un cluster existant, vérifiez qu'il répond aux exigences de la section Exigences relatives au cluster.
  • Bucket de snapshots (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éconfigurées : extrait les images publiées d'un registre de conteneurs. Comme rien n'est créé ni transféré, votre projet Google Cloud n'a pas besoin de son propre registre de conteneurs.
  • Compiler à 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.

Fonctionnement du programme d'installation

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

  • setup-gcp : crée ou valide les ressources Google Cloud requises, 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 règles IAM.
  • ate-setup : déploie les images de conteneur et les contrôleurs Agent Substrate prédéfinis sur votre cluster GKE.

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

  1. Active les API Google Cloud dont Agent Substrate a besoin.
  2. Crée un cluster GKE Standard (si vous n'en utilisez pas déjà un) avec les paramètres suivants :
    • Workload Identity Federation pour GKE : permet à Agent Substrate 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 Certificates (PodCertificateRequest et ClusterTrustBundle) : permet à ces API bêta Kubernetes d'émettre des certificats pour la communication TLS entre les composants Agent Substrate.
    • Managed OpenTelemetry : collecte les métriques et les traces de votre cluster.
  3. Crée le bucket Cloud Storage dans lequel Agent Substrate écrit vos instantanés.
  4. Accorde à Agent Substrate l'accès à Cloud Storage pour stocker les instantanés. Si vous choisissez de compiler à partir de la source, il accorde également l'accès à Artifact Registry pour les images de conteneurs.
  5. Crée des tableaux de bord Cloud Monitoring qui représentent graphiquement la latence de routage, la taille des instantanés et le trafic gRPC d'Agent Substrate.

L'installateur apporte ensuite les modifications suivantes à votre cluster :

  1. Ajoute le groupe et les ressources de l'API Agent Substrate à votre cluster. Il s'agit de ressources personnalisées Kubernetes, telles que ActorTemplate (qui définit les images de conteneurs et les ressources utilisées par vos agents) et WorkerPool (qui définit le nombre de bacs à sable inactifs à conserver).
  2. Configure les autorités de certification qui émettent les certificats identifiant les composants d'Agent Substrate et vos acteurs. Les composants présentent ces certificats pour s'authentifier mutuellement à l'aide de mTLS.
  3. Déploie les composants du sous-strat d'agent sur votre cluster, ainsi qu'une base de données PostgreSQL qui suit l'état de vos acteurs et de vos workers. 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 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 le runtime basé sur gVisor qu'Agent Substrate 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 runtimes de microVM. Pour utiliser les runtimes de 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 d'exécution des 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 de l'expiration du jeton), exécutez à nouveau la commande. Le programme d'installation conserve les ressources existantes et reprend là où il s'était arrêté.

Pour mettre à niveau Agent Substrate sur un cluster existant, exécutez le programme d'installation et sélectionnez Mettre à niveau un cluster installé. Pour en savoir plus, consultez la section Mettre à niveau un cluster installé dans le fichier README de substrate-gke.

Étapes facultatives

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

  • Pilote CSI Filestore : installe le pilote CSI Filestore configuré pour Agent Substrate. Choisissez cette option si vos agents ont besoin d'un stockage de fichiers partagé entre les pods, comme 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 de 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 en cas de pic 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émonstration 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 principaux 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

Libellés 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 installée sur votre cluster. Agent Substrate n'exécute les Workers que sur les nœuds portant ce libellé de version.

Pour vérifier la version d'Agent Substrate 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 informations suivantes concernant le libellé des nœuds :

  • Pools de nœuds de calcul : lorsque vous créez un WorkerPool, configurez-le pour qu'il cible ce tag de version. Pour obtenir des exemples, consultez Épingler des pools à la version de substrat installée dans le guide de l'API Substrate.
  • Nouveaux nœuds : le programme d'installation attribue des libellés aux nœuds individuels plutôt qu'au 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 étiqueter votre pool de nœuds GKE afin que les nouveaux nœuds reçoivent automatiquement l'étiquette.

Essayer la démo du compteur

Si vous avez choisi de déployer la démo du compteur lorsque l'installateur vous y a invité, vous pouvez observer les capacités de suspension et de restauration de l'Agent Substrate. La démo exécute un petit serveur Web qui conserve un compteur 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 prochaines étapes à suivre.

Désinstaller Agent Substrate

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 d'un cluster existant : si vous avez effectué l'installation sur un cluster existant et que vous souhaitez conserver le cluster et ses autres charges de travail, supprimez uniquement les composants Agent Substrate en exécutant la commande ate-setup delete ate-system que l'installateur affiche. Le programme d'installation préremplit cette commande avec les valeurs de projet, de cluster et d'emplacement configurées lors de l'installation.

  • Supprimez toutes les ressources (y compris le cluster) : pour supprimer le cluster GKE, le bucket de snapshots, les liaisons IAM et les tableaux de bord, exécutez la commande cleanup-gcp que l'installateur affiche. 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 de substrate-gke.

Étapes suivantes