KI-Codeausführung mit Agent Sandbox isolieren

In diesem Dokument finden Sie eine Anleitung zum Installieren und Ausführen des Agent Sandbox-Controllers in einem Google Kubernetes Engine-Cluster (GKE). Außerdem wird beschrieben, wie Sie eine Sandbox-Umgebung im Cluster bereitstellen, in der Sie nicht vertrauenswürdige Shell-Befehle testen können.

Der Agent Sandbox-Controller bietet ein Framework zum Erstellen und Verwalten von kurzlebigen Laufzeitumgebungen. So können Sie eine Vorlage für die Umgebung Ihrer App definieren und dann bei Bedarf Instanzen davon erstellen.

Agent Sandbox bietet eine sichere und isolierte Umgebung für die Ausführung nicht vertrauenswürdigen Codes, z. B. Code, der von Large Language Models (LLMs) generiert wird. Die direkte Ausführung dieser Art von Code in einem Cluster birgt Sicherheitsrisiken, da nicht vertrauenswürdiger Code möglicherweise auf andere Anwendungen oder den zugrunde liegenden Clusterknoten zugreifen oder diese beeinträchtigen kann.

Die Agent Sandbox minimiert diese Risiken, indem sie für den ausgeführten Code eine starke Prozess-, Speicher- und Netzwerkisolation bietet. Diese Isolation wird durch gVisor erreicht, einer Technologie, die eine sichere Barriere zwischen der Anwendung und dem Betriebssystem des Clusterknotens schafft. Es können auch andere Sandboxing-Technologien wie Kata-Container verwendet werden. Im Beispiel in diesem Dokument wird jedoch nur gVisor verwendet.

In diesem Dokument finden Sie eine Anleitung zum Ausführen von Agent Sandbox in einem GKE Autopilot- oder Standardcluster.

Agent Sandbox ist ein Open-Source-Projekt. Weitere Informationen dazu, wie Sie zum Projekt beitragen oder detailliertere technische Informationen finden, finden Sie hier.

Kosten

Wenn Sie die Schritte in diesem Dokument ausführen, fallen Gebühren für Ihr Google Cloud-Konto an. Die Kosten beginnen, wenn Sie einen GKE-Cluster erstellen. Diese Kosten umfassen Clustergebühren für GKE, wie auf der Preisseite beschrieben, und Gebühren für die Ausführung von Compute Engine-VMs.

Um unnötige Gebühren zu vermeiden, deaktivieren Sie GKE oder löschen Sie das Projekt, nachdem Sie dieses Dokument durchgearbeitet haben.

Hinweise

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Artifact Registry, Google Kubernetes Engine APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  4. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    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 GKE_LOCATION="us-central1"
export AGENT_SANDBOX_VERSION="v0.1.0"
export NODE_POOL_NAME="agent-sandbox-node-pool"
export MACHINE_TYPE="e2-standard-2"
export PYTHON_CLIENT_VERSION="main"

    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 wie Ihr GKE-Cluster im richtigen Projekt erstellt werden.
    • CLUSTER_NAME: der Name Ihres GKE-Cluster, z. B. agent-sandbox-cluster.
    • GKE_LOCATION: die Google Cloud Region, in der Ihr GKE-Cluster und das Artifact Registry-Repository erstellt werden, z. B. us-central1. Wir empfehlen, sie zusammen zu platzieren, da dies die Latenz beim Abrufen von Images verringert.
    • AGENT_SANDBOX_VERSION: Die Version des Agent Sandbox-Controllers, der in Ihrem Cluster bereitgestellt werden soll.
    • 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.
    • PYTHON_CLIENT_VERSION: Die Version des Python-Clients für die Agentic Sandbox, die installiert werden soll.

    Agent Sandbox bereitstellen

    Nachdem Sie Ihr Google Cloud -Projekt und Ihre Cloud Shell-Umgebung eingerichtet haben, können Sie die erforderliche Infrastruktur bereitstellen und Agent Sandbox bereitstellen.

    GKE-Cluster erstellen

    Als Nächstes erstellen Sie einen GKE-Cluster, in dem gVisor aktiviert ist. Dieser Cluster bietet die Kubernetes-Umgebung, in der Sie den Agent Sandbox-Controller und die Beispiel-Sandbox-App bereitstellen und ausführen. gVisor bietet die Sandbox-Technologie zum sicheren Ausführen von nicht vertrauenswürdigem Code.

    Sie können entweder einen Autopilot- oder einen Standardcluster erstellen. In Autopilot-Clustern wird gVisor automatisch aktiviert, während Sie in Standardclustern einen gVisor-fähigen Knotenpool manuell erstellen müssen:

    Autopilot

    Führen Sie den folgenden Befehl aus, um einen Autopilot-Cluster mit der gcloud CLI zu erstellen:

    gcloud container clusters create-auto ${CLUSTER_NAME} \
    --location=${GKE_LOCATION} \
    --project=${PROJECT_ID}

    Standard

    So erstellen Sie einen Standardcluster mit der gcloud CLI:

    1. Erstellen Sie den Cluster:

      gcloud container clusters create ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}

    2. Erstellen Sie einen separaten Knotenpool mit aktiviertem gVisor:

      gcloud container node-pools create ${NODE_POOL_NAME} \
  --cluster=${CLUSTER_NAME} \
  --location=${GKE_LOCATION} \
  --machine-type=${MACHINE_TYPE} \
  --image-type=cos_containerd \
  --sandbox type=gvisor

    Rufen Sie die Anmeldedaten des Clusters ab, damit die kubectl-Befehlszeile eine Verbindung zum Cluster herstellen kann. Mit diesem Befehl wird Ihre Kubernetes-Konfigurationsdatei aktualisiert, die standardmäßig im Verzeichnis ~/.kube/config gespeichert ist. Diese Konfigurationsdatei enthält die Anmeldedaten, die kubectl für die Interaktion mit Ihrem GKE-Cluster benötigt:

    gcloud container clusters get-credentials ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}

    Agent Sandbox-Controller in Ihrem Cluster bereitstellen

    Sie können den Agent Sandbox-Controller und die erforderlichen Komponenten bereitstellen, indem Sie die offiziellen Release-Manifeste auf Ihren Cluster anwenden. Diese Manifeste sind Konfigurationsdateien, die Kubernetes anweisen, alle erforderlichen Komponenten herunterzuladen, die zum Bereitstellen und Ausführen des Agent Sandbox-Controllers in Ihrem Cluster erforderlich sind.

    Führen Sie die folgenden Befehle aus, um den Agent Sandbox-Controller in Ihrem GKE-Cluster bereitzustellen:

    kubectl apply \
-f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/manifest.yaml \
-f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/extensions.yaml

    Agent-Sandbox-Controller prüfen

    Prüfen Sie nach dem Anwenden der Manifeste, ob der Agent Sandbox-Controller-Pod ordnungsgemäß im Namespace agent-sandbox-system ausgeführt wird:

    kubectl get pods -n agent-sandbox-system

    Warten Sie, bis in der Spalte STATUS „Running“ und in der Spalte READY „1/1“ angezeigt wird. Wenn der Pod ordnungsgemäß ausgeführt wird, sieht die Ausgabe in etwa so aus:

    NAME                         READY   STATUS    RESTARTS   AGE
agent-sandbox-controller-0   1/1     Running   0          44d

    Nachdem der Agent Sandbox-Controller ausgeführt wird, kann er automatisch Sandbox-Umgebungen für alle Sandbox-Ressourcen erstellen und verwalten, die Sie in Ihrem Cluster erstellen.

    Sandbox-Umgebung bereitstellen

    Nachdem der Agent Sandbox-Controller in Ihrem GKE-Cluster ausgeführt wird, müssen Sie die Komponenten für die Beispiel-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

    Sie definieren nun 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 vorbereiteten 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
      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"
            ephemeral-storage: "512Mi"
      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 von und zur Interaktion mit Sandbox-Umgebungen verwenden, nutzt eine Komponente namens „Sandbox Router“ für die Kommunikation mit den Sandboxes.

    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: 2 # Run at least two replicas for high availability
  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:v20251124-v0.1.0-10-ge26ddb2
        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: "250m"
            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

    Python-Client installieren

    Nachdem die In-Cluster-Komponenten wie der Sandbox-Router bereitgestellt wurden, müssen Sie als letzten Vorbereitungsschritt den Agentic Sandbox-Python-Client 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 aus dem agent-sandbox-Repository:

      pip install "git+https://github.com/kubernetes-sigs/agent-sandbox.git@${PYTHON_CLIENT_VERSION}#subdirectory=clients/python/agentic-sandbox-client"

    Sandbox testen

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

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

      from agentic_sandbox import SandboxClient

# Automatically tunnels to svc/sandbox-router-svc
with SandboxClient(
    template_name="python-runtime-template",
    namespace="default"
) as sandbox:
    print(sandbox.run("echo 'Hello from the sandboxed environment!'").stdout
)

    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 erfolgreich 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 mit der Methode sandbox.run() Bash-Shell-Befehle im sicheren Container ausgeführt. Der Client erfasst und druckt dann die stdout aus diesem Befehl. Die Sandbox wird nach Ausführung des Programms automatisch gelöscht.

    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=$GKE_LOCATION --quiet

    Nächste Schritte

    • Weitere Informationen zum Open-Source-Projekt „Agent Sandbox“ finden Sie GitHub.
    • Informationen zur zugrunde liegenden Technologie, die für die Sicherheitsisolierung Ihrer Arbeitslasten sorgt, finden Sie unter GKE Sandbox.
    • Weitere Informationen zur Verbesserung der Sicherheit für Ihre Cluster und Arbeitslasten finden Sie in der GKE-Sicherheitsübersicht.