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 Cloud de Confiance Console auf der Seite für die Projektauswahl ein Projekt aus oder erstellen Sie eines. Cloud de Confiance

    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 die Abrechnung für Ihr Cloud de Confiance Projekt 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 in der Cloud de Confiance Console Cloud Shell.

    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 Kubernetes Engine-Administrator (roles/container.admin) IAM-Rolle für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen und Verwalten von Sandboxen 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. Legen Sie in Cloud Shell die folgenden nützlichen Umgebungsvariablen fest, 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 Cloud de Confiance by S3NS 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 Cloud de Confiance by S3NS 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 Sandboxen 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 Sandboxen 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 Sandboxen 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 Sandboxen 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 Sandboxen 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 the sandboxed environment!'").stdout)
except Exception as e:
    print(f"An error occurred: {e}")

  2. Führen Sie das Testskript über Ihr Terminal aus (wobei die virtuelle Umgebung weiterhin 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 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.

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

Sandboxen in der Produktion ausführen

In diesem Dokument interagieren Sie über Cloud Shell von außerhalb des Clusters mit Sandboxen. 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 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. Beachten Sie Folgendes, wenn Sie Agent Sandbox in der Produktion verwenden möchten:

Ressourcen bereinigen

Damit Ihrem Cloud de Confiance by S3NS Konto keine 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