Agent Substrate in GKE installieren

Agent Substrate führt Agenten-Arbeitslasten effizient in GKE-Clustern aus, indem inaktive Agenten angehalten und wiederhergestellt werden, wenn sie wieder aktiv werden müssen. Agent Substrate ist eine Open-Source-Software, die Sie in einem GKE Standard-Cluster installieren können.

In diesem Dokument wird beschrieben, wie Sie Ihr Google Cloud -Projekt und Ihren GKE-Cluster für Agent Substrate vorbereiten, wie Sie das Installationsprogramm ausführen und welche Ressourcen bei der Installation erstellt werden.

Preise

Agent Substrate wird in GKE ohne zusätzliche Kosten angeboten. Die GKE-Preise gelten für die von Ihnen erstellten Ressourcen.

Beschränkungen

Für Agent Substrate gelten die folgenden Installationsbeschränkungen:

  • Cloud Shell: Sie können Agent Substrate nicht in Cloud Shell installieren, da Cloud Shell 5 GB nichtflüchtigen Speicher bietet, was für die Installation nicht ausreicht. Sie müssen das Installationsprogramm auf Ihrem lokalen Computer ausführen.
  • Clustermodus: Sie können Agent Substrate nur in GKE Standard-Clustern installieren. Autopilot-Cluster werden nicht unterstützt.
  • Vorhandene Cluster und Beta-APIs: Sie können die erforderlichen Beta-APIs (podcertificaterequests und clustertrustbundles) nicht in einem vorhandenen Cluster aktivieren. Wenn Sie die Installation in einem vorhandenen Cluster mit Version 1.36 durchführen, müssen diese APIs beim Erstellen des Clusters aktiviert worden sein.
  • Maschinentypen: Sie können keine Maschinenserien verwenden, die auf gemischten CPU-Architekturen ausgeführt werden, z. B. E2-Maschinentypen.

Hinweis

Führen Sie die folgenden Aufgaben aus, bevor Sie beginnen:

  • Aktivieren Sie die Google Kubernetes Engine API.
    • Google Kubernetes Engine API aktivieren
  • Wenn Sie die Google Cloud CLI für diese Aufgabe verwenden möchten, müssen Sie die gcloud CLI installieren und dann initialisieren. Wenn Sie die gcloud CLI bereits installiert haben, rufen Sie die neueste Version mit dem Befehl gcloud components update ab. In früheren gcloud CLI-Versionen werden die Befehle in diesem Dokument möglicherweise nicht unterstützt.
  • Installieren Sie die folgenden Komponenten in der gcloud CLI:
    • kubectl
    • gke-gcloud-auth-plugin
  • Prüfen Sie, ob die folgenden Tools auf Ihrem lokalen Computer installiert sind:
    • Git zum Klonen des Agent Substrate-Repositorys.
    • Go, um die Programme des Installationsprogramms auszuführen, die als Quellcode verteilt werden.
    • make, um das Installationsprogramm zu starten.

  • Da das Installationsprogramm in Ihrem Namen APIs aktiviert und Ressourcen bereitstellt, müssen Sie Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) einrichten. Führen Sie dazu den folgenden Befehl aus:

    gcloud auth application-default login

    Weitere Informationen zur Authentifizierung mit ADC finden Sie unter Standardanmeldedaten für Anwendungen einrichten.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, damit Sie die nötigen Berechtigungen für die Installation von Agent Substrate haben:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Clusteranforderungen

Wenn Sie den Installer einen Cluster für Sie erstellen lassen, wird automatisch ein Cluster konfiguriert, der alle Anforderungen für Agent Substrate erfüllt.

Wenn Sie Agent Substrate stattdessen auf einem vorhandenen Cluster installieren möchten, muss dieser Cluster die folgenden Anforderungen erfüllen:

  • Wird in GKE Standard ausgeführt (Agent Substrate wird nur in Standardclustern unterstützt).
  • Führt GKE-Version 1.36 (mit aktivierten Beta-Flags) oder Version 1.37 oder höher aus.
  • Verwendet c3-standard-4-Maschinentypen oder größere Maschinentypen für Knoten.
  • Die Kubernetes-APIs PodCertificateRequest und ClusterTrustBundle sind aktiviert (certificates.k8s.io/v1beta1/podcertificaterequests und certificates.k8s.io/v1beta1/clustertrustbundles). Diese APIs sind ab Kubernetes-Version 1.37 allgemein verfügbar. Das bedeutet, dass sie in allen Clustern aktiviert sind, in denen Version 1.37 oder höher ausgeführt wird. Sie müssen sie nur in vorhandenen Clustern mit Version 1.36-Patchversionen manuell aktivieren. Eine Anleitung finden Sie unter Beta APIs in einem vorhandenen Cluster aktivieren.

Agent Substrate installieren

Führen Sie den folgenden Befehl in Ihrem lokalen Terminal aus, um Agent Substrate zu installieren:

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

Das interaktive Installationsprogramm fordert Sie auf, Ihre Projekt-, Cluster- und Speichereinstellungen anzugeben. Wenn möglich, werden empfohlene Standardeinstellungen vorgeschlagen, die Sie übernehmen oder anpassen können:

  • Projekt-ID (erforderlich): Geben Sie das Google Cloud Projekt an, in dem Ressourcen bereitgestellt werden. Wenn Sie ein Standardprojekt für die gcloud CLI konfiguriert haben, verwendet das Installationsprogramm diese Projekt-ID.
  • Cluster (erforderlich): Wählen Sie aus, ob der Installer einen neuen GKE-Cluster mit empfohlenen Standardeinstellungen erstellen oder Agent Substrate in einem vorhandenen Cluster installieren soll. Wenn Sie die Installation in einem vorhandenen Cluster vornehmen, prüfen Sie, ob er die Anforderungen im Abschnitt Clusteranforderungen erfüllt.
  • Snapshot-Bucket (optional): Geben Sie einen benutzerdefinierten Namen für den Cloud Storage-Bucket an oder lassen Sie das Feld leer, damit das Installationsprogramm einen Standard-Bucket mit dem Namen ate-snapshots-<project>-<zone> erstellt.

Wenn Sie aufgefordert werden, eine Container-Image-Quelle auszuwählen, haben Sie folgende Möglichkeiten:

  • Vordefinierte Images: Ruft veröffentlichte Images aus einer Container-Registry ab. Da nichts erstellt oder übertragen wird, benötigt Ihr Google Cloud Projekt keine eigene Container Registry.
  • Aus Quelle erstellen: Die Images werden aus dem Upstream-Agent Substrate-Repository (oder einem benutzerdefinierten Branch) erstellt und per Push in die Artifact Registry Ihres Projekts übertragen.

Was das Installationsprogramm tut

Das Installationsprogramm führt die folgenden Programme in Ihrem Namen aus:

  • setup-gcp: Erstellt oder überprüft die erforderlichen Google Cloud Ressourcen, aktiviert APIs, erstellt den GKE-Cluster (wenn Sie keinen vorhandenen Cluster verwenden möchten) und den Cloud Storage-Bucket und konfiguriert IAM-Richtlinien.
  • ate-setup: Stellt die vorgefertigten Agent Substrate-Container-Images und ‑Controller in Ihrem GKE-Cluster bereit.

Zuerst nimmt das Installationsprogramm die folgenden Änderungen an Ihrem Google Cloud -Projekt vor:

  1. Aktiviert die Google Cloud APIs, die Agent Substrate benötigt.
  2. Erstellt einen GKE Standard-Cluster (falls kein vorhandener Cluster verwendet wird) mit den folgenden Einstellungen:
    • Workload Identity Federation for GKE: Ermöglicht Agent Substrate den Zugriff auf Cloud Storage, ohne dass Schlüssel auf den Knoten gespeichert werden müssen.
    • GKE Dataplane V2: Verarbeitet das Netzwerk, das zum Weiterleiten eingehender Anfragen an Ihre Agents erforderlich ist.
    • Certificate APIs (PodCertificateRequest und ClusterTrustBundle): Ermöglicht diesen Kubernetes Beta APIs, Zertifikate für die TLS-Kommunikation zwischen Agent Substrate-Komponenten auszustellen.
    • Verwaltetes OpenTelemetry: Erfasst Messwerte und Traces aus Ihrem Cluster.
  3. Erstellt den Cloud Storage-Bucket, in den Agent Substrate Ihre Snapshots schreibt.
  4. Gewährt Agent Substrate Zugriff auf Cloud Storage zum Speichern von Snapshots. Wenn Sie die Option zum Erstellen aus dem Quellcode auswählen, wird auch der Zugriff auf Artifact Registry für Container-Images gewährt.
  5. Erstellt Cloud Monitoring-Dashboards, in denen die Routing-Latenz, die Snapshot-Größe und der gRPC-Traffic von Agent Substrate dargestellt werden.

Als Nächstes nimmt das Installationsprogramm die folgenden Änderungen an Ihrem Cluster vor:

  1. Fügt Ihrem Cluster die Agent Substrate API-Gruppe und -Ressourcen hinzu. Dabei handelt es sich um benutzerdefinierte Kubernetes-Ressourcen wie ActorTemplate (definiert die Container-Images und Ressourcen, die von Ihren Agents verwendet werden) und WorkerPool (definiert, wie viele inaktive Sandboxes bereitgehalten werden).
  2. Richtet die Zertifizierungsstellen ein, die die Zertifikate ausstellen, mit denen die Komponenten von Agent Substrate und Ihre Akteure identifiziert werden. Komponenten präsentieren diese Zertifikate, um sich gegenseitig mit mTLS zu authentifizieren.
  3. Stellt die Komponenten von Agent Substrate in Ihrem Cluster bereit, zusammen mit einer PostgreSQL-Datenbank, in der der Status Ihrer Akteure und Worker erfasst wird. Das Installationsprogramm wartet, bis die Datenbank und alle Pods der Steuerungsebene bereit sind.

Agent Substrate stellt seine Komponenten als normale Arbeitslasten in den Namespaces ate-system und podcertificate-controller-system bereit. Bei der Installation wird die GKE-Steuerungsebene nicht geändert.

Zu den bereitgestellten Komponenten gehört die gVisor-basierte Laufzeit, die Agent Substrate standardmäßig verwendet, um jeden Ihrer Agents von dem Knoten zu isolieren, auf dem er ausgeführt wird. Das Installationsprogramm konfiguriert keine MicroVM-Runtimes. Wenn Sie MicroVM-Runtimes verwenden möchten, müssen Sie sie manuell in einem Knotenpool bereitstellen, in dem verschachtelte Virtualisierung aktiviert ist. Weitere Informationen finden Sie in der Anleitung zur microVM-Laufzeit im vorgelagerten Agent Substrate-Repository.

Wenn die Installation an irgendeiner Stelle fehlschlägt (z. B. aufgrund eines vorübergehenden Netzwerkfehlers oder eines abgelaufenen Tokens), führen Sie den Befehl noch einmal aus. Das Installationsprogramm behält vorhandene Ressourcen bei und wird an der Stelle fortgesetzt, an der es unterbrochen wurde.

Wenn Sie Agent Substrate auf einem vorhandenen Cluster aktualisieren möchten, führen Sie das Installationsprogramm aus und wählen Sie Vorhandenen Cluster aktualisieren aus. Weitere Informationen finden Sie in der substrate-gke-README-Datei unter Upgrading an installed cluster.

Optionale Schritte

Nach der Bereitstellung der Kernkomponenten bietet das Installationsprogramm die folgenden optionalen Schritte an:

  • Filestore-CSI-Treiber: Installiert den Filestore-CSI-Treiber, der für Agent Substrate konfiguriert ist. Wählen Sie diese Option aus, wenn Ihre Agents einen gemeinsamen Dateispeicher für alle Pods benötigen, z. B. gemeinsame Arbeitsbereiche oder Repositories. Wenn in Ihrem Cluster das verwaltete GKE Filestore-Add-on aktiviert ist, wird es vom Installationsprogramm deaktiviert, bevor der Treiber bereitgestellt wird.
  • Autoscaling von Knotenpools: Ermöglicht das Cluster-Autoscaling von GKE für Ihren Knotenpool. Sie geben die Mindest- und Höchstzahl von Knoten für den Pool an. Wählen Sie diese Option aus, wenn GKE bei Bedarf automatisch Knoten hinzufügen und Knoten entfernen soll, wenn Agents angehalten werden. Überspringen Sie diese Option, wenn Sie eine feste Anzahl von Knoten mit vorhersehbaren Rechenkosten bevorzugen.
  • Counter-Demo: Stellt eine Beispielarbeitslast bereit, die das Anhalten und Wiederherstellen von Agents demonstriert. Wählen Sie diese Option aus, wenn Sie den Cluster nach der Installation testen möchten. Weitere Informationen finden Sie unter Zähler-Demo ausprobieren.

Installation überprüfen

Führen Sie die folgenden Befehle aus, um zu prüfen, ob die Installation erfolgreich war und die Kernkomponenten ausgeführt werden. Achten Sie darauf, dass alle Pods den Status Running haben:

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

Knotenlabeling und ‑versionen

Das Installationsprogramm wendet das Label ate.dev/substrate-version auf jeden Knoten in Ihrem Cluster an. Dieses Label gibt an, welche Version von Agent Substrate in Ihrem Cluster installiert ist. Agent Substrate führt Worker nur auf Knoten mit diesem Versionslabel aus.

Führen Sie den folgenden Befehl aus, um zu prüfen, welche Version von Agent Substrate in Ihrem Cluster installiert ist:

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

Beachten Sie die folgenden Details zur Knotenbeschriftung:

  • Worker-Pools: Wenn Sie einen WorkerPool erstellen, konfigurieren Sie ihn so, dass er auf dieses Versionstag ausgerichtet ist. Beispiele finden Sie im Substrate API-Leitfaden unter Pin pools to the installed substrate version (Pools an die installierte Substratversion anpinnen).
  • Neue Knoten: Das Installationsprogramm kennzeichnet einzelne Knoten anstelle des Knotenpools. Aus diesem Grund beginnen alle nach der Installation hinzugefügten neuen Knoten – auch in einem vom Installationsprogramm erstellten Knotenpool – ohne das Versionslabel. Sie sollten Ihren GKE-Knotenpool mit einem Label versehen, damit neue Knoten automatisch das Label erhalten.

Zähler-Demo ausprobieren

Wenn Sie den Counter-Democode bereitgestellt haben, als Sie vom Installationsprogramm dazu aufgefordert wurden, können Sie die Funktionen von Agent Substrate zum Anhalten und Wiederherstellen beobachten. In der Demo wird ein kleiner Webserver ausgeführt, der einen Zähler im Arbeitsspeicher führt.

Nachdem Sie die WorkerPool und ActorTemplate des Demoprojekts bereitgestellt haben, gibt das Installationsprogramm die Befehle aus, die Sie zum Erstellen einer Actor aus der ActorTemplate und zum Senden einer Anfrage an diese Actor benötigen. In der README-Datei für die Zählerdemo im Upstream-Repository für das Agent-Substrat werden die nächsten Schritte beschrieben.

Agent Substrate deinstallieren

Wenn die Installation abgeschlossen ist und das Installationsprogramm beendet wird, gibt es benutzerdefinierte Bereinigungsbefehle für Ihre Umgebung aus.

Wählen Sie eine der folgenden Optionen aus, um Ressourcen zu entfernen, die während der Installation erstellt wurden:

  • Agent Substrate aus einem vorhandenen Cluster entfernen: Wenn Sie die Installation in einem vorhandenen Cluster durchgeführt haben und den Cluster und seine anderen Arbeitslasten beibehalten möchten, löschen Sie nur die Agent Substrate-Komponenten. Führen Sie dazu den ate-setup delete ate-system-Befehl aus, der vom Installationsprogramm ausgegeben wird. Das Installationsprogramm füllt diesen Befehl mit den während der Installation konfigurierten Werten für Projekt, Cluster und Standort vorab aus.

  • Alle Ressourcen löschen (einschließlich des Clusters): Wenn Sie den GKE-Cluster, den Snapshot-Bucket, die IAM-Bindungen und die Dashboards löschen möchten, führen Sie den cleanup-gcp-Befehl aus, den das Installationsprogramm ausgibt. Das Installationsprogramm füllt diesen Befehl mit den während der Installation konfigurierten Werten für Projekt, Cluster, Standort und Bucket vorab aus. Weitere Informationen finden Sie im Abschnitt „Tearing down“ der README-Datei für substrate-gke.

Nächste Schritte