Sandboxes für Dienste konfigurieren

Cloud Run-Sandboxes bieten eine schnelle, sichere und isolierte Umgebung zum Ausführen von nicht vertrauenswürdigem Code oder zum Ausführen von Tools wie KI-Agents in Ihrem vorhandenen Dienst in der Umgebung der zweiten Generation. Sandboxes sind stark auf Latenz optimiert und werden in derselben Instanz wie Ihr Container ausgeführt. Dabei werden die zugewiesene CPU und der zugewiesene Arbeitsspeicher gemeinsam genutzt.

Auf dieser Seite wird beschrieben, wie Sie Sandboxes in Ihrem Container konfigurieren. Weitere Informationen zum Schreiben von Code für die Interaktion mit der Sandbox über die Befehlszeile finden Sie unter Codeausführung in Cloud Run.

Hinweis

  1. Melden Sie sich in Ihrem Google Cloud Konto an. Wenn Sie noch kein Konto haben Google Cloud, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

  2. 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

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

  4. 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

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

  6. Installieren und initialisieren Sie die gcloud CLI.
  7. Stellen Sie einen Cloud Run-Dienst in der Ausführungsumgebung der zweiten Generation bereit.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Konfigurieren und Bereitstellen von Cloud Run-Diensten benötigen:

Wenn Sie einen Dienst oder eine Funktion aus dem Quellcode bereitstellen, müssen Ihnen außerdem zusätzliche Rollen für Ihr Projekt und das Cloud Build-Dienstkonto zugewiesen werden.

Eine Liste der IAM-Rollen und -Berechtigungen im Zusammenhang mit Cloud Run finden Sie unter IAM-Rollen für Cloud Run und IAM-Berechtigungen für Cloud Run. Wenn Ihr Cloud Run-Dienst mit Google Cloud APIs wie Cloud-Clientbibliotheken verknüpft ist, lesen Sie die Konfigurationsanleitung für Dienstidentitäten. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Bereitstellungsberechtigungen und Zugriff verwalten.

Sandboxes aktivieren

Jede Konfigurationsänderung führt zur Erstellung einer neuen Überarbeitung. Für nachfolgende Überarbeitungen gilt automatisch dieselbe Konfigurationseinstellung, sofern Sie sie nicht explizit aktualisieren.

Wenn Sie Sandboxes aktivieren, wird Ihr Cloud Run-Dienst in der Ausführungsumgebung der zweiten Generation bereitgestellt. Verwenden Sie die Google Cloud CLI oder eine YAML-Konfiguration, um Sandboxes in Cloud Run-Diensten zu aktivieren:

gcloud

Geben Sie das Flag --sandbox-launcher an, um den Dienst bereitzustellen oder zu aktualisieren:

  • Führen Sie den folgenden Befehl aus, um einen neuen Dienst bereitzustellen:

    gcloud beta run deploy SERVICE --image IMAGE_URL --sandbox-launcher

    Ersetzen Sie Folgendes:

    • SERVICE: der Name Ihres Cloud Run-Dienstes.
    • IMAGE_URL: ein Verweis auf das Container-Image, zum Beispiel us-docker.pkg.dev/cloudrun/container/hello:latest. Wenn Sie Artifact Registry, das Repository REPO_NAME muss bereits erstellt sein. Die URL hat das Format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.

  • Führen Sie den folgenden Befehl aus, um einen vorhandenen Dienst zu aktualisieren:

    gcloud beta run services update SERVICE --sandbox-launcher

YAML

  1. Wenn Sie einen neuen Dienst erstellen, überspringen Sie diesen Schritt. Wenn Sie einen vorhandenen Dienst aktualisieren, laden Sie die zugehörige YAML-Konfiguration herunter:

    gcloud run services describe SERVICE --format export > service.yaml

  2. Aktualisieren Sie die YAML-Datei Ihres Dienstes, um das Attribut sandboxLauncher mit dem Wert true in die Containerkonfiguration aufzunehmen:

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  annotations:
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    spec:
      containers:
      - name: CONTAINER
        image: IMAGE_URL
        sandboxLauncher: true
        port: 8080

    Ersetzen Sie Folgendes:

    • SERVICE: der Name Ihres Cloud Run-Dienstes.
    • CONTAINER: der Name Ihres Containers.
    • IMAGE_URL: ein Verweis auf das Container-Image, zum Beispiel us-docker.pkg.dev/cloudrun/container/hello:latest. Wenn Sie Artifact Registry, das Repository REPO_NAME muss bereits erstellt sein. Die URL hat das Format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.

  3. Erstellen oder aktualisieren Sie den Dienst mit dem folgenden Befehl:

    gcloud run services replace service.yaml

    Der Befehl gcloud run services replace verwendet standardmäßig die Datei service.yaml, falls vorhanden.

Sandboxes verwenden dieselbe CPU und denselben Arbeitsspeicher, die dem Hostcontainer zugewiesen sind. Achten Sie darauf, dass die Limits für CPU und Arbeitsspeicher Ihres Hauptcontainers sowohl für Ihre Anwendung als auch für alle aktiven Sandboxes ausreichen, die Sie gleichzeitig ausführen.

Sandboxes deaktivieren

Verwenden Sie die Google Cloud CLI oder eine YAML-Konfiguration, um die Möglichkeit zu deaktivieren, eine Sandbox in Ihrem Dienst zu starten:

gcloud

Aktualisieren Sie den Dienst mit dem Flag --no-sandbox-launcher, indem Sie den folgenden Befehl ausführen:

gcloud beta run services update SERVICE --no-sandbox-launcher

Ersetzen Sie SERVICE durch den Namen Ihres Dienstes.

YAML

  1. Wenn Sie einen neuen Dienst erstellen, überspringen Sie diesen Schritt. Wenn Sie einen vorhandenen Dienst aktualisieren, laden Sie die zugehörige YAML-Konfiguration herunter:

    gcloud run services describe SERVICE --format export > service.yaml

  2. Aktualisieren Sie die YAML-Datei Ihres Dienstes, um das Attribut sandboxLauncher aus der Containerkonfiguration zu entfernen:

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
spec:
  template:
    spec:
      containers:
      - name: CONTAINER
        image: IMAGE_URL
        port: 8080

    Ersetzen Sie Folgendes:

    • SERVICE: der Name Ihres Cloud Run-Dienstes.
    • CONTAINER: der Name Ihres Containers.
    • IMAGE_URL: ein Verweis auf das Container-Image, zum Beispiel us-docker.pkg.dev/cloudrun/container/hello:latest. Wenn Sie Artifact Registry, das Repository REPO_NAME muss bereits erstellt sein. Die URL hat das Format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.

  3. Erstellen oder aktualisieren Sie den Dienst mit dem folgenden Befehl:

    gcloud run services replace service.yaml

    Der Befehl gcloud run services replace verwendet standardmäßig die Datei service.yaml, falls vorhanden.

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.

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

Node.js

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

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

Python

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

import subprocess
result = subprocess.run(
    ["/usr/local/gcp/bin/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 über eine Go-Anwendung auszuführen:

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

Sandbox-Befehlszeile

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

/usr/local/gcp/bin/sandbox do -- /bin/echo "Hello"

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

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

Informationen zum Ausführen von nicht vertrauenswürdigem Code in einer Sandbox über Ihren Dienst finden Sie unter Codeausführung in Cloud Run.