Codeausführung in Cloud Run

Vorabversion – Cloud Run-Sandboxes

Diese Funktion unterliegt den „Bedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA‑Funktionen stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie unter den Beschreibungen der Startphase.

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

Wichtigste Vorteile

Cloud Run-Sandboxen bieten die folgenden wichtigen Vorteile:

• Schnelle Erstellung: Sandboxen sind interaktiv und können fast sofort Befehle ausführen. Wenn Sie Sandboxes in einer vorhandenen Cloud Run-Ressource erstellen, in der Ihr Agent ausgeführt wird, verkürzen Sie die Erstellungszeiten im Vergleich zum Erstellen einer neuen Cloud Run-Ressource für jede Aufgabe. Diese Effizienz trägt dazu bei, dass Ihr Agent reaktionsfähig bleibt.

• Sicherheit: Sandboxes isolieren die Prozessausführung. Standardmäßig haben Sandboxen keinen Zugriff auf die übergeordnete Arbeitslast, Umgebungsvariablen, Secrets oder den Google Cloud -Metadatenserver. Alle Sandboxes sind vollständig 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 sitzungsgebunden und wird nach Abschluss gelöscht. Sie können jedoch nichtflüchtige Verzeichnisse oder Snapshots verwenden, um bestimmte Arbeitsbereiche zu speichern oder Daten einem Cloud Storage-Bucket zuzuordnen.

Hinweis

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.
   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

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

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 zu erhalten:

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

Sandboxes starten

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

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

Sie können die Binärdatei ausführen, indem Sie in Ihrem Quellcode auf ihren absoluten Pfad verweisen. Wenn Sie beispielsweise Hello in Ihrer isolierten Sandbox ausgeben möchten, wählen Sie eine der folgenden Optionen aus:

Node.js

Fügen Sie den folgenden Code ein, um den Sandbox-Befehl aus einer Node.js-Anwendung auszuführen:

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

Python

Fügen Sie den folgenden Code ein, um den Sandbox-Befehl aus einer Python-Anwendung auszuführen:

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

Go

Fügen Sie den folgenden Code ein, um den Sandbox-Befehl aus einer Go-Anwendung auszuführen:

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

Sandbox-CLI

Führen Sie den folgenden Befehl aus, um den Sandbox-Befehl direkt über die Befehlszeile auszuführen:

sandbox do -- /bin/echo "Hello"

Führen Sie den Befehl sandbox -h aus, um die vollständige Liste der verfügbaren Befehle aufzurufen.

Befehlszeilenfunktionen der Sandbox 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 Anweisung in einer neuen, temporären 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 ausfü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:

Node.js

So führen Sie den Sandbox-Befehl über eine Node.js-Anwendung aus:

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

Python

So führen Sie den Sandbox-Befehl über eine Python-Anwendung aus:

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}

Go

So führen Sie den Sandbox-Befehl über eine Go-Anwendung aus:

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

Sandbox-CLI

So führen Sie den Sandbox-Befehl direkt über die Befehlszeile aus:

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

Wenn Sie einen Befehl anhand seines Namens ohne 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 innerhalb derselben Cloud Run-Instanz hinweg beibehalten möchten, können Sie den Dateisystemstatus des Arbeitsbereichs mithilfe von Standard-tar-Archivdateien importieren und exportieren. Alternativ können Sie Bind-Bereitstellungen konfigurieren, um Verzeichnisse direkt zwischen dem Hostcontainer 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 vor der Ausführung Dateien aus einer tar-Archivdatei in die Sandbox.
• --sync-tar: Führt eine bidirektionale Synchronisierung durch, indem vor der Ausführung importiert und nach Abschluss exportiert wird.

Das Verzeichnis /tmp in der Sandbox ist nicht Teil des Root-Dateisystem-Overlays. Archivdateien enthalten daher keine Dateien, die in /tmp geschrieben wurden. Wenn Sie Daten persistent speichern möchten, schreiben Sie sie in ein anderes Verzeichnis, z. B. /workspace.

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 /workspace && echo 'task-complete' > /workspace/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 /workspace/status.txt"
   

Alternativ können Sie --sync-tar=/tmp/work.tar verwenden, um den vorhandenen Archivstatus automatisch zu importieren und neue Änderungen in einem einzigen Befehl zu exportieren. Wenn ein Sandbox-Prozess beendet wird, löscht Cloud Run die sitzungsspezifischen Overlay-Dateien, die nicht in eine Archivdatei exportiert wurden, endgültig.

Befehl im Hintergrund ausführen

Wenn Sie lang laufende Prozesse, monitorlose Browser oder Hintergrundserver ausführen möchten, z. B. eine Hintergrund-Agentenschleife, die kontinuierlich auf eingehende Anfragen wartet, verwenden Sie das Flag --detach.

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 verwenden. 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 den Namen der Sandbox an.

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

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

Umgebungsvariablen konfigurieren

Konfigurieren Sie Umgebungsvariablen in Sandboxen wie in jedem anderen Container. Sandboxes übernehmen keine Umgebungsvariablen vom 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 mit dem Flag env, da sie für die Sandbox-Prozesse sichtbar sein könnten.

Dateisystem-Snapshots erstellen

Sie können eine benannte Sandbox im Hintergrund bereitstellen, um kontinuierliche Aufgaben wie Webserver oder lang laufende Agent-Workflows zu verarbeiten, Befehle dynamisch für die Sandbox auszuführen und den geänderten Dateisystemstatus in einer tar-Archivdatei zu erfassen.

Tipp: Wenn Sie viele Befehle wiederholt in einer einzelnen Sandbox ausführen, sollten Sie die Sandbox einmal mit einem inaktiven Einstiegspunkt wie sleep 12m starten und dann den Befehl sandbox exec ausführen, der auf diese Sandbox abzielt, um die Befehle sehr schnell auszuführen.

Wenn Sie beispielsweise eine Hintergrund-Sandbox bereitstellen, eine Datei in ihr Overlay schreiben und einen Snapshot des Status erstellen 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. Schreiben Sie die Datei in einen Pfad außerhalb von /tmp, da Dateien, die in /tmp innerhalb der Sandbox geschrieben werden, nicht in Snapshots erfasst werden:

   sandbox run --write my-sandbox --detach -- /usr/bin/bash -c "echo 'hi' > /workspace/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 folgende Ergebnisse sehen:

   ./
   ./workspace/
   ./workspace/hello.txt
   

Netzwerk konfigurieren

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

Führen Sie beispielsweise den folgenden Befehl aus, um Daten von einem externen Endpunkt abzurufen:

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 auf eine erfolgreiche Verbindung hinweist.

Auf das Dateisystem zugreifen

Standardmäßig haben Prozesse, die Sie in der Sandbox ausführen, nur Lesezugriff auf das Root-Dateisystem des Hostcontainers. 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-Bereitstellungen konfigurieren.

Das Verzeichnis /tmp in der Sandbox ist immer beschreibbar, auch ohne das Flag --write. Das Verzeichnis /tmp wird gelöscht, wenn die Sandbox gelöscht wird. Es ist nicht in Snapshots oder Archivdateien enthalten.

Standardmäßiger Lesezugriff

Innerhalb der Sandbox können Prozesse Dateien aus dem Hostcontainer lesen, aber nicht in das Stammdateisystem außerhalb von /tmp 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 standardmäßigen Lesezugriff zu prüfen:

1. Erstellen Sie ein Python-Skript im Hostcontainer:

   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, 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 das Stammverzeichnis (/) in der Standard-Sandbox 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' > /testfile.txt"
   

   Der Befehl schlägt mit dem folgenden Fehler fehl:

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

Daten mithilfe von Bind-Bereitstellungen freigeben

Wenn Sie Prozessen in der Sandbox erlauben möchten, persistente Daten zu schreiben, hängen Sie ein freigegebenes Volume mit dem Flag --mount an:

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

   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 Sandbox die Datei erfolgreich geändert hat:

   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 und gleichzeitig explizit verhindern möchten, dass Dateien geändert werden, hängen Sie das Attribut readonly an die Bereitstellungsspezifikation an.

Führen Sie beispielsweise den folgenden Befehl aus, um Schreibbeschränkungen für eine schreibgeschützte Bind-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 Ausführungsstarts und -beendigungen 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:

Node.js

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);

Python

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

Go

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-Agenten in Cloud Run
• Browser- und Betriebssystemautomatisierung in Cloud Run
• Lesen Sie den Containerlaufzeitvertrag.