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 Open-Source-Software, die Sie in einem GKE-Standardcluster 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: 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 installieren. Auf Knoten, die vor dem Update erstellt wurden, ist die Pod-Zertifikatprojektion 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, 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).
  • GKE-Version 1.36 (mit aktivierten Beta-Flags) oder Version 1.37 oder höher.
  • 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: Nach dem Aktivieren der APIs müssen Sie die vorhandenen Knoten ersetzen, z. B. durch ein Upgrade des Knotenpools oder durch erneutes Erstellen der Knoten. Die Pod-Zertifikatprojektion ist auf Knoten, die vor dem Update (MountVolume.SetUp failed: unimplemented) vorhanden waren, nicht aktiviert.
    • Version 1.37 oder höher: Die Pod-Zertifikatprojektion ist auf vorhandenen Knoten bereits aktiviert. Sie müssen Knoten also nicht ersetzen, nachdem Sie die APIs aktiviert haben.

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, die Einstellungen für Ihr Projekt, Ihren Cluster und Ihren Speicher 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 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 ü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 in die Artifact Registry-Registry Ihres Projekts.

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-Föderation für 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 API-Gruppe und Ressourcen von Agent Substrate hinzu. Dies sind benutzerdefinierte Kubernetes-Ressourcen wie ActorTemplate (die die Container-Images und Ressourcen definiert, die von Ihren Agents verwendet werden) und WorkerPool (die 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-Laufzeiten. Wenn Sie MicroVM-Runtimes verwenden möchten, müssen Sie sie manuell in einem Knotenpool bereitstellen, für den die verschachtelte Virtualisierung aktiviert ist. Weitere Informationen finden Sie in der microVM-Laufzeitanleitung im Upstream-Repository für das 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 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 Upgrade an installed cluster (Installierten 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 Kundenservicemitarbeiter 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öchstanzahl 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.
  • Zählerdemo: 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

Knotenlabel 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.
  • Neue Knoten: Das Installationsprogramm kennzeichnet einzelne Knoten und nicht den Knotenpool. 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 die Zählerdemo bereitgestellt haben, als Sie vom Installationsprogramm dazu aufgefordert wurden, können Sie sehen, wie Agent Substrate die Aussetzung und Wiederherstellung von Agenten handhabt. In der Demo wird ein kleiner Webserver ausgeführt, der einen Zähler im Arbeitsspeicher führt.

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

Agent Substrate deinstallieren

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

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

  • 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, 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 Projekt-, Cluster- und Standortwerten 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 für substrate-gke.

Nächste Schritte