Agent Substrate in GKE installieren

Agent Substrate on GKE ermöglicht die effiziente Ausführung agentischer Arbeitslasten in GKE-Clustern, indem inaktive Agenten angehalten und wiederhergestellt werden, wenn sie wieder aktiv werden müssen. Agent Substrate on GKE ist Open-Source-Software, die Sie in einem GKE Standard-Cluster installieren können.

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

Preise

Agent Substrate on GKE wird ohne Aufpreis angeboten. Die GKE-Preise gelten für die von Ihnen erstellten Ressourcen.

Beschränkungen

Für die Installation von Agent Substrate on GKE gelten die folgenden Einschränkungen:

  • Cloud Shell: Sie können Agent Substrate on GKE nicht in Cloud Shell installieren, da Cloud Shell 5 GB nichtflüchtigen Speicher bietet, der für die Installation nicht ausreicht. Sie müssen das Installationsprogramm auf Ihrem lokalen Computer ausführen.
  • Clustermodus: Sie können Agent Substrate on GKE nur in GKE Standard-Clustern installieren. Autopilot-Cluster werden nicht unterstützt.
  • Vorhandene Cluster und Beta APIs: Wenn Sie die erforderlichen Beta APIs (podcertificaterequests und clustertrustbundles) in einem vorhandenen Cluster mit Version 1.36 aktivieren, müssen Sie die vorhandenen Knoten ersetzen, bevor Sie Agent Substrate on GKE installieren. Für Knoten, die vor dem Update erstellt wurden, ist die Pod-Zertifikatsprojektion nicht aktiviert (MountVolume.SetUp failed: unimplemented). In Clustern mit Version 1.37 oder höher müssen vorhandene Knoten nicht ersetzt werden.
  • 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, installieren und dann initialisieren Sie die gcloud CLI. Wenn Sie die gcloud CLI bereits installiert haben, rufen Sie die neueste Version mit dem gcloud components update Befehl ab. Ältere Versionen der gcloud CLI unterstützen möglicherweise nicht die Ausführung der Befehle in diesem Dokument.
  • Installieren Sie die folgenden Komponenten in der gcloud CLI:
    • kubectl
    • gke-gcloud-auth-plugin
  • Achten Sie darauf, dass die folgenden Tools auf Ihrem lokalen Computer installiert sind:
    • Git zum Klonen des Agent Substrate-Repositorys.
    • Gehen Sie zum Ausführen der Programme des Installationsprogramms, die als Quellcode verteilt werden.
    • make zum Starten des Installationsprogramms.

  • Da das Installationsprogramm in Ihrem Namen APIs aktiviert und Ressourcen bereitstellt, richten Sie Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) ein, indem Sie den folgenden Befehl ausführen:

    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 Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Installieren von Agent Substrate on GKE, benötigen:

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 das Installationsprogramm einen Cluster für Sie erstellen lassen, wird automatisch ein Cluster konfiguriert, der alle Anforderungen für Agent Substrate on GKE erfüllt.

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

  • Wird in GKE Standard ausgeführt (Agent Substrate on GKE wird nur in Standard-Clustern unterstützt).
  • Wird mit GKE-Version 1.36 (mit aktivierten Beta-Flags) oder Version 1.37 oder höher ausgeführt.
  • Verwendet c3-standard-4 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). Führen Sie den folgenden Befehl aus, um diese APIs in einem vorhandenen Cluster zu aktivieren:

    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: Nachdem Sie die APIs aktiviert haben, müssen Sie die vorhandenen Knoten ersetzen, z. B. indem Sie den Knotenpool upgraden oder seine Knoten neu erstellen. Die Pod-Zertifikatsprojektion ist für Knoten, die vor dem Update vorhanden waren, nicht aktiviert (MountVolume.SetUp failed: unimplemented).
    • Version 1.37 oder höher: Die Pod-Zertifikatsprojektion ist bereits für vorhandene Knoten aktiviert. Sie müssen Knoten also nicht ersetzen, nachdem Sie die APIs aktiviert haben.

Agent Substrate on GKE installieren

Führen Sie den folgenden Befehl in Ihrem lokalen Terminal aus, um Agent Substrate on GKE 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. Es schlägt nach Möglichkeit empfohlene Standardeinstellungen vor, die Sie akzeptieren 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 das Installationsprogramm einen neuen GKE-Cluster mit empfohlenen Standardeinstellungen erstellen oder Agent Substrate on GKE in einem vorhandenen Cluster installieren soll. Wenn Sie die Installation in einem vorhandenen Cluster auswählen, prüfen Sie, ob er die Anforderungen im Abschnitt Clusteranforderungen erfüllt.
  • Snapshot-Bucket (optional): Geben Sie einen benutzerdefinierten Cloud Storage Bucket-Namen 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 per Push übertragen wird, benötigt Ihr Google Cloud Projekt keine eigene Container-Registry.
  • Aus Quelle erstellen: Erstellt die Images aus dem Upstream- Agent Substrate-Repository (oder einem benutzerdefinierten Branch) und überträgt sie per Push an die Artifact Registry Ihres Projekts.

Funktionsweise des Installationsprogramms

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

  • setup-gcp: Erstellt oder prüft die erforderlichen Google Cloud Ressourcen, aktiviert APIs, erstellt den GKE-Cluster (wenn Sie keinen vorhandenen Cluster verwenden) und den Cloud Storage-Bucket und konfiguriert IAM-Richtlinien.
  • ate-setup: Stellt die vordefinierten Agent Substrate on GKE-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 für Agent Substrate on GKE erforderlich sind.
  2. Erstellt einen GKE Standard-Cluster (wenn kein vorhandener Cluster verwendet wird) mit den folgenden Einstellungen:
    • Workload Identity Federation for GKE: Ermöglicht Agent Substrate on GKE den Zugriff auf Cloud Storage, ohne Schlüssel auf den Knoten zu speichern.
    • GKE Dataplane V2: Verarbeitet die Netzwerkkonfiguration, die erforderlich ist, um eingehende Anfragen an Ihre Agenten weiterzuleiten.
    • Zertifikat-APIs (PodCertificateRequest und ClusterTrustBundle): Aktiviert diese Kubernetes Beta APIs, um Zertifikate für die TLS-Kommunikation zwischen Agent Substrate on GKE-Komponenten auszustellen.
    • Verwaltetes OpenTelemetry: Erfasst Messwerte und Traces aus Ihrem Cluster.
  3. Erstellt den Cloud Storage-Bucket, in den Agent Substrate on GKE Ihre Snapshots schreibt.
  4. Gewährt Agent Substrate on GKE Zugriff auf Cloud Storage zum Speichern von Snapshots. Wenn Sie die Option „Aus Quelle erstellen“ auswählen, wird auch Zugriff auf Artifact Registry für Container-Images gewährt.
  5. Erstellt Cloud Monitoring-Dashboards, in denen die Routing-Latenz von Agent Substrate on GKE, die Snapshot-Größe und der gRPC-Traffic dargestellt werden.

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

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

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

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

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 setzt die Installation an der Stelle fort, an der sie unterbrochen wurde.

Wenn Sie Agent Substrate on GKE in einem vorhandenen Cluster upgraden möchten, führen Sie das Installationsprogramm aus und wählen Sie Upgrade an installed cluster aus. Weitere Informationen finden Sie in der README-Datei unter substrate-gke 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 on GKE konfiguriert ist. Wählen Sie diese Option aus, wenn Ihre Agenten einen gemeinsamen Dateispeicher für Pods benötigen, z. B. gemeinsame Arbeitsbereiche oder Repositorys. Wenn das verwaltete GKE Filestore-Add-on in Ihrem Cluster aktiviert ist, deaktiviert das Installationsprogramm es, bevor der Treiber bereitgestellt wird.
  • Autoscaling von Knotenpools: Aktiviert das GKE Cluster-Autoscaling für Ihren Knotenpool. Sie geben die Mindest- und Höchstanzahl der Knoten für den Pool an. Wählen Sie diese Option aus, wenn GKE bei Nachfragespitzen automatisch Knoten hinzufügen und Knoten entfernen soll, wenn Agenten angehalten werden. Überspringen Sie diese Option, wenn Sie eine feste Anzahl von Knoten mit vorhersehbaren Compute-Kosten bevorzugen.
  • Zählerdemo: Stellt eine Beispielarbeitslast bereit, die das Anhalten und Wiederherstellen von Agenten demonstriert. Wählen Sie diese Option aus, wenn Sie den Cluster nach der Installation testen möchten. Weitere Informationen finden Sie unter Zählerdemo 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 on GKE in Ihrem Cluster installiert ist. Agent Substrate on GKE 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 on GKE in Ihrem Cluster installiert ist:

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

Beachten Sie die folgenden Details zum Knotenlabeling:

  • 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 Pools an die installierte Substrate-Version anpinnen.
  • Neue Knoten: Das Installationsprogramm labelt einzelne Knoten und nicht den Knoten pool. Daher starten alle nach der Installation hinzugefügten Knoten – auch in einem vom Installationsprogramm erstellten Knotenpool – ohne das Versionslabel. Sie sollten Ihren GKE-Knoten pool labeln, damit neue Knoten automatisch das Label erhalten.

Zählerdemo ausprobieren

Wenn Sie die Zählerdemo bereitgestellt haben, als Sie vom Installationsprogramm dazu aufgefordert wurden, können Sie die Funktionen zum Anhalten und Wiederherstellen von Agent Substrate on GKE beobachten. Die Demo führt einen kleinen Webserver aus, der einen Zähler im Arbeitsspeicher führt.

Nachdem Sie das WorkerPool und das ActorTemplate der Demo bereitgestellt haben, gibt das Installationsprogramm die Befehle aus, die Sie zum Erstellen eines Actor aus dem ActorTemplate und zum Senden einer Anfrage an diesen Actor benötigen. Die README-Datei zur Zählerdemo im Upstream-Repository von Agent Substrate enthält die nächsten Schritte.

Agent Substrate on GKE deinstallieren

Nach Abschluss der Installation gibt das Installationsprogramm angepasste Bereinigungsbefehle für Ihre Umgebung aus.

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

  • Agent Substrate on GKE 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 on GKE-Komponenten, indem Sie den ate-setup delete ate-system Befehl ausführen, den das Installationsprogramm ausgibt. 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 Befehl cleanup-gcp 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 zu substrate-gke.

Nächste Schritte