KI-Codeausführung mit Agent Sandbox isolieren

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

Eine Übersicht darüber, wie die Agent Sandbox-Funktion nicht vertrauenswürdigen, KI-generierten Code isoliert, finden Sie unter 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 Google Cloud -Projekt aus oder erstellen Sie eines.

    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 jedes 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 Berechtigung resourcemanager.projects.create enthält. Weitere 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. Weitere 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 Feature „Agent Sandbox“ aktiviert ist. Wenn Sie noch 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 Ihr 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, die Sie in diesem Dokument ausführen, zu vereinfachen, 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 finden Sie 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 (z. B. us-central1) fest, wenn Sie einen Autopilot-Cluster verwenden, oder auf die Zone (z. B. us-central1-a), wenn Sie einen Standardcluster 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 handelt sich um 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 Beispiel in diesem Dokument erstellt der Client mit dem Befehl kubectl port-forward einen Tunnel zu diesem Router, sodass Sie keine öffentlichen IP-Adressen offenlegen müssen. Die Verwendung von kubectl port-forward ist keine sichere Lösung und sollte auf Entwicklungsumgebungen beschränkt werden.

SandboxTemplate und SandboxWarmPool erstellen

Jetzt definieren Sie die Konfiguration für Ihre Sandbox, indem Sie eine SandboxTemplate- und eine SandboxWarmPool-Ressource erstellen. Die SandboxTemplate dient als wiederverwendbarer Blueprint, mit dem der Agent Sandbox-Controller konsistente, vorkonfigurierte Sandbox-Umgebungen erstellt. Die SandboxWarmPool-Ressource sorgt dafür, dass immer eine bestimmte Anzahl von vorab aufgewärmten Pods ausgeführt wird und bereit ist, in Anspruch genommen zu werden. Eine vorab aufgewärmte Sandbox ist ein laufender Pod, der bereits initialisiert wurde. Durch diese Vorinitialisierung können neue Sandboxes in weniger als einer Sekunde erstellt werden. Außerdem wird die Startlatenz beim Starten einer regulären Sandbox 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 das 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, nutzt 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 herzustellen, der im Cluster ausgeführt wird. Bei diesem Tunneling-Ansatz ist keine öffentliche IP-Adresse oder komplexe Ingress-Einrichtung erforderlich. Außerdem wird die Interaktion mit Sandboxes über Ihre lokale Umgebung vereinfacht.

So stellen Sie den Sandbox-Router bereit:

  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 das Sandbox Router-Deployment korrekt ausgeführt wird:

    kubectl get deployment sandbox-router-deployment

    Warten Sie, bis in der Spalte READY 2/2 oder 1/1 angezeigt wird.

Python-Client installieren

Nachdem die In-Cluster-Komponenten wie der Sandbox-Router bereitgestellt wurden, müssen Sie als letzten Vorbereitungsschritt die Agentic Sandbox-Python-Clientbibliothek auf Ihrem lokalen Computer installieren. Dieser Client ist eine Python-Bibliothek, mit der Sie Sandboxes programmatisch erstellen, verwenden und löschen können. Sie verwenden sie im nächsten Abschnitt, 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 in Ihrem Verzeichnis agent-sandbox ein Python-Script mit dem Namen test_sandbox.py und 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 the sandboxed environment!'").stdout)
except Exception as e:
    print(f"An error occurred: {e}")

  2. Führen Sie das Testskript über das Terminal aus (die virtuelle Umgebung muss weiterhin aktiv sein):

    python3 test_sandbox.py

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

Glückwunsch! Sie haben einen Shell-Befehl in einer sicheren Sandbox ausgeführt. Mit der Methode sandbox.run() können Sie beliebige Shell-Befehle ausführen. Die Agent Sandbox führt den Befehl innerhalb einer sicheren Barriere aus, die die Knoten Ihres Clusters und andere Arbeitslasten vor nicht vertrauenswürdigem Code schützt. So können KI-Agents oder automatisierte Workflows Aufgaben sicher und zuverlässig ausführen.

Wenn Sie das Skript ausführen, werden alle Schritte von SandboxClient übernommen. Dabei wird die SandboxClaim-Ressource erstellt, um die Sandbox zu starten. Es wird gewartet, bis die Sandbox bereit ist, und dann wird die Methode sandbox.run() verwendet, um Bash-Shell-Befehle im sicheren Container auszuführen. Der Client erfasst und druckt dann den stdout aus diesem Befehl. Die Sandbox wird nach Ausführung des Programms automatisch gelöscht.

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

Um zu prüfen, ob eine bestimmte Sandbox beansprucht oder verfügbar ist, sehen Sie sich die ownerReferences in den Metadaten des Sandbox-Pods an. Wenn der Wert des Felds kind Sandbox ist, wird der Pod verwendet. Wenn der Wert des Felds kind SandboxWarmPool ist, ist der Pod im Leerlauf und wartet darauf, dass er beansprucht wird.

Sandboxen in der Produktionsumgebung ausführen

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

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

  • 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 Controller-Anwendung ausgeführt wird:

    • Wenn die Controlleranwendung als Pod im selben Cluster ausgeführt wird, verwenden Sie Kubernetes RBAC oder die 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 erteilen.
    • 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 Controller-Anwendung müssen den Sandbox-Router in Ihrem Cluster erreichen. Verwenden Sie in der Produktion eine der folgenden Methoden, um eine Netzwerkverbindung herzustellen:

    • Wenn die Controller-Anwendung 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 Anwendungsbeispielen 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 Google Cloud APIs wie Cloud Storage senden muss, verwenden Sie eine IAM-Richtlinie mit Workload Identity-Föderation für GKE, um dem Kubernetes-Dienstkonto, das der Sandbox-Pod verwendet, die für diesen Zugriff erforderlichen Berechtigungen zu erteilen.

Ressourcen bereinigen

Um zu vermeiden, dass Ihrem Google Cloud -Konto Gebühren in Rechnung gestellt werden, sollten Sie den erstellten GKE-Cluster löschen:

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

Nächste Schritte