KI-Codeausführung mit Agent Sandbox isolieren

In diesem Dokument finden Sie eine Anleitung zum Bereitstellen einer Entwicklungsumgebung und zum Verwenden des Agent Sandbox Python-Clients in einem Google Kubernetes Engine-Cluster (GKE).

Eine Übersicht darüber, wie das Agent Sandbox-Feature nicht vertrauenswürdigen, von KI generierten Code isoliert, finden Sie unter Informationen zu GKE Agent Sandbox.

Kosten

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

Hinweis

  1. Wählen Sie in der Google Cloud Console auf der Seite für die Projektauswahl ein Projekt aus oder erstellen Sie eines. Google Cloud

    Rollen, die zum Auswählen oder Erstellen eines Projekts erforderlich sind

    • Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können ein beliebiges Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
    • Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die resourcemanager.projects.create Berechtigung enthält. Informationen zum Zuweisen von Rollen.

    Zur Projektauswahl

  2. Prüfen Sie, ob für Ihr Google Cloud Projekt die Abrechnung aktiviert ist.

  3. Aktivieren Sie die Artifact Registry API und die Kubernetes Engine API.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Informationen zum Zuweisen von Rollen.

    APIs aktivieren

  4. Aktivieren Sie Cloud Shell in der Google Cloud Console.

    Cloud Shell aktivieren

  5. Prüfen Sie, ob Sie die Berechtigungen haben, die für diese Anleitung erforderlich sind.
  6. Sie benötigen einen GKE-Cluster, in dem das Agent Sandbox-Feature aktiviert ist. Wenn Sie keinen haben, folgen Sie der Anleitung unter Agent Sandbox in GKE aktivieren, um einen neuen Cluster zu erstellen oder einen vorhandenen zu aktualisieren.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle „Kubernetes Engine-Administrator “ (roles/container.admin) für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen und Verwalten von Sandboxes 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.

Umgebungsvariablen definieren

Um die Befehle zu vereinfachen, die Sie in diesem Dokument ausführen, können Sie Umgebungsvariablen in Cloud Shell festlegen. Definieren Sie in Cloud Shell die folgenden nützlichen Umgebungsvariablen, indem Sie die folgenden Befehle ausführen:

export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export LOCATION="us-central1"
export NODE_POOL_NAME="agent-sandbox-node-pool"
export MACHINE_TYPE="e2-standard-2"

Hier eine Erläuterung dieser Umgebungsvariablen:

  • PROJECT_ID: die ID Ihres aktuellen Google Cloud Projekts. Durch das Definieren dieser Variablen wird sichergestellt, dass alle Ressourcen, z. B. Ihr GKE-Cluster, im richtigen Projekt erstellt werden.
  • CLUSTER_NAME: der Name Ihres GKE-Cluster, z. B. agent-sandbox-cluster.
  • LOCATION: die Google Cloud Region oder Zone, in der sich Ihr GKE Cluster befindet. Legen Sie dies auf die Region fest (z. B. us-central1), wenn Sie einen Autopilot-Cluster verwenden, oder auf die Zone (z. B. us-central1-a), wenn Sie einen Standard-Cluster verwenden.
  • NODE_POOL_NAME: der Name des Knotenpools, in dem Sandbox-Arbeitslasten ausgeführt werden, z. B. agent-sandbox-node-pool.
  • MACHINE_TYPE: der Maschinentyp der Knoten in Ihrem Knotenpool, z. B. e2-standard-2. Weitere Informationen zu den verschiedenen Maschinenserien und zur Auswahl zwischen verschiedenen Optionen finden Sie im Leitfaden zu Ressourcen und Vergleichen für Maschinenfamilien.

Sandbox-Umgebung bereitstellen

In diesem Abschnitt erfahren Sie, wie Sie den Sandbox-Blueprint (SandboxTemplate) erstellen, den erforderlichen Netzwerkrouter bereitstellen und den Python-Client installieren, mit dem Sie mit der Sandbox interagieren.

Die empfohlene Methode zum Erstellen und Interagieren mit Ihrer Sandbox ist die Verwendung des Agentic Sandbox Python-Clients. Dieser Client bietet eine Schnittstelle, die den gesamten Lebenszyklus einer Sandbox vereinfacht, von der Erstellung bis zur Bereinigung. Es ist eine Python-Bibliothek, mit der Sie Sandboxes programmatisch erstellen, verwenden und löschen können.

Der Client verwendet einen Sandbox-Router als zentralen Einstiegspunkt für den gesamten Traffic. Im in diesem Dokument beschriebenen Beispiel erstellt der Client mit dem Befehl kubectl port-forward einen Tunnel zu diesem Router, sodass Sie keine öffentlichen IP-Adressen freigeben müssen. Die Verwendung von kubectl port-forward ist keine sichere Lösung und sollte auf Entwicklungsumgebungen beschränkt sein.

SandboxTemplate und SandboxWarmPool erstellen

Sie definieren jetzt die Konfiguration für Ihre Sandbox, indem Sie eine SandboxTemplate- und eine SandboxWarmPool-Ressource erstellen. SandboxTemplate dient als wiederverwendbarer Blueprint, mit dem der Agent Sandbox-Controller konsistente, vorkonfigurierte Sandbox-Umgebungen erstellen kann. Die SandboxWarmPool-Ressource sorgt dafür, dass immer eine bestimmte Anzahl von vorgewärmten Pods ausgeführt wird und bereit ist, in Anspruch genommen zu werden. Eine vorgewärmte Sandbox ist ein ausgeführter Pod, der bereits initialisiert wurde. Durch diese Vorinitialisierung können neue Sandboxes in weniger als einer Sekunde erstellt werden und die Startlatenz beim Starten einer regulären Sandbox wird vermieden:

  1. Erstellen Sie in Cloud Shell eine Datei namens sandbox-template-and-pool.yaml mit folgendem Inhalt:

    apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
  name: python-runtime-template
  namespace: default
spec:
  podTemplate:
    metadata:
      labels:
        sandbox: python-sandbox-example
    spec:
      runtimeClassName: gvisor
      automountServiceAccountToken: false # Required
      securityContext:
        runAsNonRoot: true # Required
      nodeSelector:
        sandbox.gke.io/runtime: gvisor # Required
      tolerations:
      - key: "sandbox.gke.io/runtime"
        value: "gvisor"
        effect: "NoSchedule" # Required
      containers:
      - name: python-runtime
        image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
        ports:
        - containerPort: 8888
        readinessProbe:
          httpGet:
            path: "/"
            port: 8888
          initialDelaySeconds: 0
          periodSeconds: 1
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
          limits:
            cpu: "500m"
            memory: "1Gi" # Required
        securityContext:
          capabilities:
            drop: ["ALL"] # Required
      restartPolicy: "OnFailure"
---
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxWarmPool
metadata:
  name: python-sandbox-warmpool
  namespace: default
spec:
  replicas: 2
  sandboxTemplateRef:
    name: python-runtime-template

  2. Wenden Sie das SandboxTemplate- und SandboxWarmPool-Manifest an:

    kubectl apply -f sandbox-template-and-pool.yaml

Sandbox-Router bereitstellen

Der Python-Client, den Sie zum Erstellen und Interagieren mit Sandbox-Umgebungen verwenden, verwendet eine Komponente namens Sandbox-Router, um mit den Sandboxes zu kommunizieren.

In diesem Beispiel verwenden Sie den Entwicklermodus des Clients zum Testen. Dieser Modus ist für die lokale Entwicklung vorgesehen und verwendet den Befehl kubectl port-forward, um einen direkten Tunnel von Ihrem lokalen Computer zum Sandbox-Router-Dienst zu erstellen, der im Cluster ausgeführt wird. Dieser Tunnelansatz macht eine öffentliche IP-Adresse oder eine komplexe Ingress-Einrichtung überflüssig und vereinfacht die Interaktion mit Sandboxes aus Ihrer lokalen Umgebung.

Führen Sie die folgenden Schritte aus, um den Sandbox-Router bereitzustellen:

  1. Erstellen Sie in Cloud Shell eine Datei namens sandbox-router.yaml mit folgendem Inhalt:

    # A ClusterIP Service to provide a stable endpoint for the router pods.
apiVersion: v1
kind: Service
metadata:
  name: sandbox-router-svc
  namespace: default
spec:
  type: ClusterIP
  selector:
    app: sandbox-router
  ports:
  - name: http
    protocol: TCP
    port: 8080 # The port the service will listen on
    targetPort: 8080 # The port the router container listens on (from the sandbox_router/Dockerfile)
---
# The Deployment to manage and run the router pods.
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sandbox-router-deployment
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: sandbox-router
  template:
    metadata:
      labels:
        app: sandbox-router
    spec:
      # Ensure pods are spread across different zones for HA
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: topology.kubernetes.io/zone
          whenUnsatisfiable: ScheduleAnyway
          labelSelector:
            matchLabels:
              app: sandbox-router
      containers:
      - name: router
        image: us-central1-docker.pkg.dev/k8s-staging-images/agent-sandbox/sandbox-router:latest-main
        ports:
        - containerPort: 8080
        readinessProbe:
          httpGet:
            path: /healthz
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
        livenessProbe:
          httpGet:
            path: /healthz
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 10
        resources:
          requests:
            cpu: "100m"
            memory: "512Mi"
          limits:
            cpu: "1000m"
            memory: "1Gi"
      securityContext:
        runAsUser: 1000
        runAsGroup: 1000

  2. Wenden Sie das Manifest an, um den Router in Ihrem Cluster bereitzustellen:

    kubectl apply -f sandbox-router.yaml

  3. Prüfen Sie, ob die Sandbox-Router-Bereitstellung ordnungsgemäß ausgeführt wird:

    kubectl get deployment sandbox-router-deployment

    Warten Sie, bis in der Spalte READY für die Bereitstellung 2/2 oder 1/1 angezeigt wird.

Python-Client installieren

Nachdem die Clusterkomponenten wie der Sandbox-Router bereitgestellt wurden, besteht der letzte vorbereitende Schritt darin, den Agentic Sandbox Python-Client auf Ihrem lokalen Computer zu installieren. Dieser Client ist eine Python-Bibliothek, mit der Sie Sandboxes programmatisch erstellen, verwenden und löschen können. Im nächsten Abschnitt verwenden Sie ihn, um die Umgebung zu testen:

  1. Erstellen und aktivieren Sie eine virtuelle Python-Umgebung:

    python3 -m venv .venv
source .venv/bin/activate

  2. Installieren Sie das Clientpaket:

    pip install k8s-agent-sandbox

Sandbox testen

Nachdem alle Einrichtungskomponenten vorhanden sind, können Sie jetzt mit dem Agentic Sandbox Python-Client eine Sandbox erstellen und mit ihr interagieren.

  1. Erstellen Sie im Verzeichnis agent-sandbox ein Python-Skript namens test_sandbox.py mit folgendem Inhalt:

    from k8s_agent_sandbox import SandboxClient
from k8s_agent_sandbox.models import SandboxLocalTunnelConnectionConfig

# Automatically tunnels to svc/sandbox-router-svc
client = SandboxClient(
    connection_config=SandboxLocalTunnelConnectionConfig()
)

sandbox = client.create_sandbox(template="python-runtime-template", namespace="default")
try:
    print(sandbox.commands.run("echo 'Hello from Local!'").stdout)
except Exception as e:
    print(f"An error occurred: {e}")

  2. Führen Sie das Testskript über Ihr Terminal aus (während die virtuelle Umgebung noch aktiv ist):

    python3 test_sandbox.py

Jetzt sollten Sie die Meldung „Hello from the sandboxed environment!“ sehen, die von der Sandbox ausgegeben wird.

Glückwunsch! Sie haben erfolgreich einen Shell-Befehl in einer sicheren Sandbox ausgeführt. Mit der Methode sandbox.run() können Sie einen beliebigen Shell-Befehl ausführen. Agent Sandbox führt den Befehl innerhalb einer sicheren Barriere aus, die die Knoten und andere Arbeitslasten Ihres Clusters vor nicht vertrauenswürdigem Code schützt. Dies bietet eine sichere und zuverlässige Möglichkeit für einen KI-Agenten oder einen automatisierten Workflow, Aufgaben auszuführen.

Wenn Sie das Skript ausführen, übernimmt der SandboxClient alle Schritte für Sie. Er erstellt die Ressource SandboxClaim, um die Sandbox zu starten, wartet, bis die Sandbox bereit ist, und verwendet dann die Methode sandbox.run(), um Bash-Shell-Befehle im sicheren Container auszuführen. Der Client erfasst und gibt dann stdout aus diesem Befehl aus. Die Sandbox wird nach Ausführung des Programms automatisch gelöscht.

Wenn eine SandboxClaim-Ressource erstellt wird, wird ein verfügbarer Pod aus dem Warm Pool dem Sandbox-Objekt zugewiesen und der Anspruch wird als bereit markiert. Der SandboxWarmPool füllt sich dann automatisch wieder auf, um die konfigurierte Anzahl von Replikaten beizubehalten.

Wenn Sie prüfen möchten, ob eine bestimmte Sandbox in Anspruch genommen oder verfügbar ist, sehen Sie sich die ownerReferences in den Metadaten des Sandbox-Pods an. Wenn der Wert des Felds kind gleich Sandbox ist, wird der Pod verwendet. Wenn der Wert des Felds kind gleich SandboxWarmPool ist, ist der Pod inaktiv und wartet darauf, in Anspruch genommen zu werden.

Sandboxes in der Produktion ausführen

In diesem Dokument interagieren Sie über Cloud Shell von außerhalb des Clusters mit Sandboxes. Der Python-Client verwendet Ihre Nutzeranmeldedaten, um sich beim Cluster zu authentifizieren und Sandbox-Ressourcen zu verwalten, und verwendet den Befehl kubectl port-forward, um eine Verbindung mit Sandboxes herzustellen. Diese Schritte eignen sich gut für Entwicklungsszenarien.

In einem Produktionsszenario ist eine Controlleranwendung (z. B. ein KI-Orchestrator) für das Erstellen und Verwalten von Sandbox-Ressourcen verantwortlich. Beachten Sie Folgendes, wenn Sie Agent Sandbox in der Produktion verwenden möchten:

  • Authentifizierung: Ihre Controlleranwendung muss sich beim Cluster-API-Server authentifizieren, um Sandboxes auszuführen. Wie Sie die Authentifizierung konfigurieren, hängt davon ab, wo die Controlleranwendung ausgeführt wird. Hier einige Beispiele:

    • Wenn die Controlleranwendung als Pod im selben Cluster ausgeführt wird, verwenden Sie Kubernetes RBAC oder Workload Identity Federation for GKE mit IAM-Richtlinien, um dem Kubernetes Dienstkonto des Pods die erforderlichen Berechtigungen zum Beobachten von Sandboxes oder zum Ermitteln von Netzwerkendpunkten zu gewähren.
    • Wenn die Controlleranwendung außerhalb des Clusters ausgeführt wird, verwenden Sie die Workload Identity-Föderation, oder IAM-Dienstkonten, um der Anwendung eine Identität zu geben, auf die Sie in Zulassungsrichtlinien verweisen können.

  • Routing: Anfragen vom Python-Client in Ihrer Controlleranwendung müssen den Sandbox-Router in Ihrem Cluster erreichen. Verwenden Sie in der Produktion eine der folgenden Methoden, um eine Netzwerkverbindung herzustellen:

    • Wenn die Controlleranwendung im selben Cluster ausgeführt wird, verwenden Sie die Funktion SandboxDirectConnectionConfig, um die URL und den Port anzugeben, die vom Sandbox-Router-Dienst verwendet werden.
    • Wenn die Controlleranwendung außerhalb des Clusters ausgeführt wird, verwenden Sie die GKE Gateway API um einen internen oder externen Load-Balancer zu erstellen. Verwenden Sie in Ihrem Clientcode die Funktion SandboxGatewayConnectionConfig, um auf Ihr Gateway zu verweisen.

    Weitere Informationen zu diesen Routingmethoden finden Sie in den Nutzungsbeispielen auf GitHub und in den Schritten zur Gateway-Bereitstellung für den Router.

  • Sandbox-Zugriff auf Google Cloud Ressourcen: Wenn Ihr Sandbox-Code Anfragen an APIs wie Cloud Storage senden muss, verwenden Sie eine IAM-Richtlinie mit der Workload Identity-Föderation für GKE, um dem Kubernetes-Dienstkonto, das vom Sandbox-Pod verwendet wird, die für diesen Zugriff erforderlichen Berechtigungen zu erteilen. Google Cloud

Ressourcen bereinigen

Löschen Sie den erstellten GKE-Cluster, damit Ihrem Google Cloud Konto keine Gebühren in Rechnung gestellt werden:

gcloud container clusters delete $CLUSTER_NAME --location=$LOCATION --quiet

Nächste Schritte