Codeausführung in Cloud Run

Mit Cloud Run-Sandboxes können Sie nicht vertrauenswürdigen Code in einer isolierten Umgebung direkt in Containerarbeitslasten ausführen. Mit dieser Funktion können KI-Agents sicher Sub-Agents ausführen, Rechenaufgaben ausführen oder automatisierte Browser starten, ohne das Hostsystem zu gefährden.

Wichtigste Vorteile

Cloud Run-Sandboxes bieten die folgenden wichtigen Vorteile:

• Schnelle Erstellung: Sandboxes sind interaktiv und können Befehle fast sofort ausführen. Wenn Sie Sandboxes in einer vorhandenen Cloud Run-Ressource erstellen, in der Ihr KI-Agent ausgeführt wird, verkürzt sich die Erstellungszeit im Vergleich zum Erstellen einer neuen Cloud Run-Ressource für jede Aufgabe. So bleibt Ihr Agent reaktionsfähig.

• Sicherheit: Sandboxes isolieren die Prozessausführung. Standardmäßig haben Sandboxes keinen Zugriff auf die übergeordnete Arbeitslast, Umgebungsvariablen, Secrets oder den Cloud de Confiance by S3NS Metadatenserver. Alle Sandboxes sind voneinander isoliert.

• Zugriffssteuerung und Umgebung: Prozesse werden mit sudo-Berechtigungen als Nicht-Root-Nutzer ausgeführt. So können Sie während der Ausführung Tools mit Paketmanagern wie apt, pip oder npm installieren. Die Sandbox-Umgebung ist zwar kurzlebig und wird nach Abschluss gelöscht, Sie können aber persistente Verzeichnisse oder Snapshots verwenden, um bestimmte Arbeitsbereiche zu speichern oder Kartendaten einem Cloud Storage-Bucket zuzuordnen.

Hinweis

1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance 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 Cloud de Confiance project.

3. Installieren und initialisieren Sie die gcloud CLI.
4. Stellen Sie eine Cloud Run-Ressource wie einen Dienst der 2. Generation , einen Job, einen Worker-Pool oder eine Instanz bereit.

Sandboxes aktivieren

Wenn Sie Sandboxes verwenden möchten, müssen Sie sie zuerst für Ihre Cloud Run-Ressource mit dem Flag --sandbox-launcher oder dem YAML-Attribut sandboxLauncher aktivieren. Wählen Sie einen der folgenden Ressourcentypen aus, um detaillierte Konfigurationsschritte aufzurufen:

• Dienste
• Jobs
• Worker-Pools
• Instanzen (Vorschau)

Sandboxes starten

Nachdem Sie Sandboxes aktiviert haben, können Sie sie in Ihrer Containerausführungsumgebung starten. Die Sandbox-Binärdatei befindet sich unter /usr/local/gcp/bin/sandbox.

In den Beispielen in dieser Anleitung wird der Befehl sandbox anstelle des absoluten Pfads /usr/local/gcp/bin/sandbox verwendet.

Sie können das Binärprogramm ausführen, indem Sie in Ihrem Quellcode auf seinen absoluten Pfad verweisen. Wenn Sie beispielsweise Hello in Ihrer isolierten Sandbox ausgeben möchten, haben Sie folgende Möglichkeiten:

exec(`sandbox do -- /bin/echo "Hello"`, (e, stdout, stderr) => {
    res.send({ stdout, stderr });
});

import subprocess
result = subprocess.run(
    ["sandbox", "do", "--", "/bin/echo", "Hello"],
    capture_output=True,
    text=True,
)
return {"stdout": result.stdout, "stderr": result.stderr}

cmd := exec.Command("sandbox", "do", "--", "/bin/echo", "Hello")
out, err := cmd.CombinedOutput()

sandbox do -- /bin/echo "Hello"

Wenn Sie die vollständige Liste der verfügbaren Befehle aufrufen möchten, führen Sie den Befehl sandbox -h aus.

Sandbox-Befehlszeilenfunktionen verwenden

Das sandbox-Befehlszeilentool enthält Befehle zum Ausführen, Konfigurieren und Verwalten von Sandboxes.

Befehl in der Sandbox ausführen

Mit dem Befehl sandbox do können Sie eine Anleitung in einer neuen, kurzlebigen Sandbox ausführen. Mit dem Befehl sandbox do werden folgende Aufgaben ausgeführt:

1. Erstellt eine Sandbox-Umgebung (sandbox run).
2. Führt den von Ihnen angegebenen Befehl (sandbox exec) aus.
3. Löscht die Sandbox nach erfolgreicher Ausführung (sandbox delete).

Wenn Sie beispielsweise eine mathematische Berechnung in der Sandbox durchführen möchten, führen Sie die folgenden Code-Snippets für Ihre bevorzugte Sprache aus. Achten Sie darauf, dass alle Befehle oder Tools, die Sie ausführen, z. B. python3, in Ihrem Container-Image installiert sind:

exec(`sandbox do -- /usr/bin/python3 -c "print(1+2)"`, (e, stdout, stderr) => {
    res.send({ stdout, stderr });
});

import subprocess
result = subprocess.run(
    ["sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)"],
    capture_output=True,
    text=True,
)
return {"stdout": result.stdout, "stderr": result.stderr}

cmd := exec.Command("sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)")
out, err := cmd.CombinedOutput()

sandbox do -- /usr/bin/python3 -c "print(1+2)"

Wenn Sie einen Befehl über den Namen ohne den absoluten Pfad ausführen, z. B. python3 anstelle von /usr/bin/python3, konfigurieren Sie die Umgebungsvariable PATH in der Sandbox explizit mit dem Flag --env.

Daten über verschiedene Ausführungen hinweg beibehalten

Sandboxes sind standardmäßig sitzungsspezifisch. Wenn Sie Daten über verschiedene Sandbox-Ausführungen hinweg in derselben Cloud Run-Instanz persistent speichern möchten, können Sie den Zustand des Arbeitsbereich-Dateisystems mithilfe von Standardarchivdateien im tar-Format importieren und exportieren. Alternativ können Sie Bind-Mounts konfigurieren, um Verzeichnisse direkt zwischen dem Host-Container und den Sandbox-Umgebungen freizugeben.

Verwenden Sie die folgenden Flags, wenn Sie den Befehl sandbox do ausführen:

• --export-tar: Erfasst geänderte Overlay-Dateien nach Abschluss in einer tar-Archivdatei.
• --import-tar: Extrahiert Dateien aus einer tar-Archivdatei in die Sandbox, bevor die Ausführung erfolgt.
• --sync-tar: Führt eine bidirektionale Synchronisierung durch, indem vor der Ausführung importiert und nach Abschluss exportiert wird.

Wenn Sie beispielsweise Daten zwischen zwei Sandbox-Aufrufen mithilfe von Archivdateien übergeben möchten, führen Sie die folgenden Befehle aus:

1. Daten in eine Sandbox schreiben und den Status in eine Archivdatei exportieren:

   sandbox do --write --export-tar=/tmp/work.tar \
     -- /usr/bin/bash -c "mkdir -p /tmp/work && echo 'task-complete' > /tmp/work/status.txt"
   

2. Importieren Sie die Archivdatei in einem nachfolgenden Aufruf, um die Daten abzurufen:

   sandbox do --write --import-tar=/tmp/work.tar \
     -- /usr/bin/bash -c "cat /tmp/work/status.txt"
   

Alternativ können Sie mit --sync-tar=/tmp/work.tar den vorhandenen Archivstatus automatisch importieren und neue Änderungen in einem einzigen Befehl exportieren. Wenn ein Sandbox-Prozess beendet wird, löscht Cloud Run temporäre Overlay-Dateien, die nicht in eine Archivdatei exportiert wurden, dauerhaft.

Befehl im Hintergrund ausführen

Verwenden Sie das Flag --detach, um lang laufende Prozesse, monitorlose Browser oder Hintergrundserver auszuführen, z. B. eine Hintergrund-Agentenschleife, die kontinuierlich auf eingehende Anfragen wartet.

Führen Sie beispielsweise den folgenden Befehl aus, um eine getrennte Sandbox mit einem inaktiven oder Hintergrundprogramm zu starten:

sandbox run my-web-server --detach -- /usr/bin/long_running_or_idle_program

Mit dem Flag detach können Sie dieselbe Sandbox für mehrere Tests wiederverwenden. Wenn Sie mit einer ausgeführten, getrennten Sandbox interagieren oder zusätzliche Befehle darin ausführen möchten, verwenden Sie den Befehl sandbox exec und geben Sie die Sandbox anhand ihres Namens an.

Wenn Sie beispielsweise einen Testbefehl in Ihrer vorhandenen my-web-server-Hintergrund-Sandbox ausführen möchten, verwenden Sie den folgenden Befehl:

sandbox exec my-web-server -- /usr/bin/python3 -c "print('test-complete')"

Umgebungsvariablen konfigurieren

Umgebungsvariablen lassen sich in Sandboxes genauso konfigurieren wie in jedem anderen Container. Sandboxen übernehmen keine Umgebungsvariablen aus dem Hostcontainer. Sie müssen sie explizit mit dem Flag --env angeben, wenn Sie den Befehl sandbox ausführen.

Wenn Sie beispielsweise eine Konfigurationsvariable an eine Sandbox übergeben möchten, führen Sie den folgenden Befehl aus:

sandbox do --env AGENT_MODE="test" -- /usr/bin/bash -c "echo \$AGENT_MODE"

Vermeiden Sie die Übergabe von Secrets über das Flag env, da sie für die Sandbox-Prozesse sichtbar sein könnten.

Dateisystem-Snapshots erstellen

Stellen Sie eine benannte Sandbox im Hintergrund bereit, um kontinuierliche Aufgaben wie Webserver oder lang andauernde Agent-Workflows zu verarbeiten, führen Sie Befehle dynamisch in der Sandbox aus und erfassen Sie den geänderten Dateisystemstatus in einer tar-Archivdatei.

Wenn Sie beispielsweise eine Hintergrund-Sandbox bereitstellen, eine Datei in ihr Overlay schreiben und ihren Status erfassen möchten, um zu prüfen, ob die Daten erfasst wurden, führen Sie die folgenden Befehle aus:

1. Stellen Sie eine benannte Sandbox im Hintergrund mit aktiviertem Schreibzugriff bereit und erstellen Sie eine Datei in ihrem Arbeitsbereich:

   sandbox run --write my-sandbox --detach -- /usr/bin/bash -c "echo 'hi' > /tmp/hello.txt && sleep 1h"
   

2. Erstellen Sie mit dem Befehl sandbox tar einen Snapshot des geänderten Dateisystems der laufenden Sandbox:

   sandbox tar my-sandbox --file=/tmp/foo.tar
   

3. Extrahieren Sie die Snapshot-Archivdatei und prüfen Sie, ob sie die in der Sandbox geschriebenen Daten enthält:

   tar -xvf /tmp/foo.tar
   

   Sie sollten die folgenden Ergebnisse sehen:

   ./
   ./tmp/
   ./tmp/hello.txt
   

Netzwerk konfigurieren

Standardmäßig wird der gesamte ausgehende Traffic aus der Sandbox blockiert. Verwenden Sie das Flag --allow-egress, um den ausgehenden Netzwerkzugriff zuzulassen:

Wenn Sie beispielsweise Daten von einem externen Endpunkt abrufen möchten, führen Sie den folgenden Befehl aus:

sandbox do --allow-egress -- /usr/bin/python3 -c 'import urllib.request; print(urllib.request.urlopen("https://google.com").getcode())'

Dieser Befehl gibt den Standard-HTTP-Statuscode 200 zurück, der eine erfolgreiche Verbindung angibt.

Auf das Dateisystem zugreifen

Standardmäßig haben Prozesse, die Sie in der Sandbox ausführen, schreibgeschützten Zugriff auf das Root-Dateisystem des Host-Containers. Mit dem Flag --write können Sie das Schreiben in ein temporäres Dateisystem-Overlay (tmpfs) aktivieren. Die Schreibvorgänge gehen jedoch verloren, wenn die Sandbox gelöscht wird. Wenn Sie das dauerhafte Schreiben in den Hostcontainer aktivieren möchten, können Sie Bind-Mounts konfigurieren.

Standardmäßiger Lesezugriff

In der Sandbox können Prozesse Dateien aus dem Hostcontainer lesen, aber nicht in das Stammdateisystem schreiben.

In den folgenden Beispielen wird davon ausgegangen, dass Sie Befehle im Stammverzeichnis (/) Ihres Hostcontainers ausführen.

Führen Sie die folgenden Befehle aus, um den schreibgeschützten Standardzugriff zu prüfen:

1. Erstellen Sie ein Python-Script im Host-Container:

   mkdir -p /tmp/my-scripts
   echo "print('hi')" > /tmp/my-scripts/task.py
   

2. Prüfen Sie, ob die Datei lokal vorhanden ist:

   cat /tmp/my-scripts/task.py
   

3. Führen Sie die Datei in Ihrer Sandbox aus:

   sandbox do -- /usr/bin/python3 /tmp/my-scripts/task.py
   

   Dieser Befehl gibt hi zurück und bestätigt damit, dass die Sandbox Lesezugriff hat.

   Wenn Sie versuchen, Daten ohne zusätzliche Konfiguration direkt in das Stammdateisystem der Sandbox zu schreiben, schlägt die Ausführung fehl. Wenn Sie beispielsweise versuchen, in der Standardsandbox in /tmp zu schreiben, wird ein Fehler für ein schreibgeschütztes Dateisystem zurückgegeben:

   Führen Sie den folgenden Befehl aus, um in das Stammdateisystem zu schreiben:

   sandbox do -- /usr/bin/bash -c "echo 'hi' > /tmp/testfile.txt"
   

   Der Befehl schlägt mit dem folgenden Fehler fehl:

   /usr/bin/bash: line 1: /tmp/testfile.txt: Read-only file system
   Error: failed to exec in container: cmd.Wait(exec) failed: exit status 1
   

Daten mit Bind-Mounts freigeben

Wenn Prozesse innerhalb der Sandbox persistierbare Daten schreiben dürfen, hängen Sie mit dem Flag --mount ein freigegebenes Volume an:

1. Erstellen Sie ein freigegebenes Volume-Verzeichnis im Hostcontainer und füllen Sie es mit einer Startdatei:

   mkdir -p /tmp/my-volume
   echo 'read' > /tmp/my-volume/readwrite.txt
   

2. Führen Sie die Sandbox aus, um die Datei aus dem Bind-Mount-Pfad zu lesen:

   sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount -- /usr/bin/bash -c "cat /mnt/my-mount/readwrite.txt"
   

   Dieser Befehl gibt read zurück.

3. Führen Sie die Sandbox aus, um neue Daten aus dem Mount zurück auf den Host zu schreiben:

   sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount -- /usr/bin/bash -c "echo 'write' > /mnt/my-mount/readwrite.txt"
   

4. Prüfen Sie im Hostcontainer, ob die Datei in der Sandbox erfolgreich geändert wurde:

   cat /tmp/my-volume/readwrite.txt
   

   Dieser Befehl gibt write zurück.

Lesezugriff-Bereitstellungen konfigurieren

Wenn Sie der Sandbox Zugriff auf ein Hostverzeichnis gewähren, aber explizit verhindern möchten, dass Dateien geändert werden, hängen Sie das Attribut readonly an die Mount-Spezifikation an.

Führen Sie beispielsweise den folgenden Befehl aus, um Schreibbeschränkungen für eine schreibgeschützte Bind-Mount-Bereitstellung zu testen:

sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount,readonly -- /usr/bin/bash -c "echo 'fails' > /mnt/my-mount/hello.txt"

Der Schreibversuch schlägt mit dem folgenden Fehler fehl:

/usr/bin/bash: line 1: /mnt/my-mount/hello.txt: Read-only file system
Error: failed to exec in container: cmd.Wait(exec) failed: exit status 1

Logs ansehen

Cloud Run erfasst automatisch Sandbox-Lifecycle-Events wie Start und Beenden der Ausführung in Cloud Logging.

Die sandbox-Befehlszeile schreibt die Standardausgabe (stdout) und den Standardfehler (stderr) von Sandbox-Befehlen direkt in die Standardstreams des aufrufenden Prozesses. Wenn Sie diese Logs in Cloud Logging aufrufen möchten, leiten Sie die Streams an die Standardausgabe und den Standardfehler Ihres Containers weiter:

const { exec } = require('child_process');
const child = exec('sandbox do -- /usr/bin/python3 -c "print(1+2)"');
child.stdout.pipe(process.stdout);
child.stderr.pipe(process.stderr);

subprocess.run(
    ["sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)"],
    stdout=sys.stdout,
    stderr=sys.stderr,
)

cmd := exec.Command("sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)")
cmd.Stdout = os.Stdout
cmd.Stderr = os.Stderr
cmd.Run()

Nächste Schritte

• Weitere Informationen zum Hosten von KI-Agents in Cloud Run
• Browser- und Betriebssystemautomatisierung in Cloud Run
• Containerlaufzeitvertrag