Exécution de code dans Cloud Run

Cloud Run est déjà mis en bac à sable et isolé, ce qui en fait une plate-forme idéale pour héberger des agents d'IA. Lorsque vous activez les bacs à sable Cloud Run, l'outil de ligne de commande sandbox devient disponible dans votre conteneur. Utilisez cet outil en ligne de commande pour exécuter du code non fiable écrit dans n'importe quel langage, dans un environnement bac à sable hautement optimisé, isolé du reste de votre conteneur.

Les agents d'IA peuvent utiliser des bacs à sable pour exécuter des sous-agents, effectuer des tâches de calcul ou ouvrir des navigateurs dans un environnement rapide et isolé, sans risquer d'endommager le système hôte.

Les bacs à sable Cloud Run offrent les principaux avantages suivants :

  • Création rapide : les bacs à sable sont interactifs et prêts à exécuter des commandes presque instantanément. En créant des bacs à sable dans une ressource Cloud Run existante où votre agent s'exécute, vous réduisez les temps de création par rapport à la création d'une ressource Cloud Run pour chaque tâche. Cette efficacité permet de garantir que votre agent reste réactif.

  • Sécurité : les bacs à sable isolent l'exécution des processus. Par défaut, les bacs à sable n'ont pas accès à la charge de travail parente, aux variables d'environnement, aux secrets ni au serveur de métadonnées Google Cloud . Toutes les bacs à sable sont complètement isolés les uns des autres.

  • Contrôle des accès et environnement : les processus s'exécutent avec des privilèges sudo en tant qu'utilisateur non root, ce qui vous permet d'installer des outils à l'aide de gestionnaires de packages tels que apt, pip ou npm lors de l'exécution. Bien que l'environnement de bac à sable soit éphémère et supprimé une fois l'atelier terminé, vous pouvez utiliser des répertoires persistants ou des instantanés pour enregistrer des ateliers spécifiques ou mapper des données sur un bucket Cloud Storage.

Avant de commencer

  1. Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

  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. Installez et initialisez la gcloud CLI.
  7. Déployez un service Cloud Run dans l'environnement d'exécution de deuxième génération.

Activer les bacs à sable

Lorsque vous activez les bacs à sable, votre service Cloud Run est déployé dans l'environnement d'exécution de deuxième génération. Pour activer les bacs à sable dans les services Cloud Run, utilisez la Google Cloud CLI ou une configuration YAML :

gcloud

Pour déployer ou mettre à jour le service, spécifiez l'option --sandbox-launcher :

  • Pour déployer un nouveau service, exécutez la commande suivante :

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

    Remplacez les éléments suivants :

    • SERVICE : nom de votre service Cloud Run.
    • IMAGE_URL : référence à l'image de conteneur, par exemple us-docker.pkg.dev/cloudrun/container/hello:latest. Si vous utilisez Artifact Registry, le dépôt REPO_NAME doit déjà être créé. L'URL est au format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.

  • Pour mettre à jour un service existant, exécutez la commande suivante :

    gcloud beta run services update SERVICE --sandbox-launcher

YAML

  1. Si vous créez un service, ignorez cette étape. Si vous mettez à jour un service existant, téléchargez sa configuration YAML :

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

  2. Mettez à jour le fichier YAML de votre service pour inclure l'attribut sandboxLauncher défini sur true dans la configuration de votre conteneur :

    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

    Remplacez les éléments suivants :

    • SERVICE : nom de votre service Cloud Run.
    • CONTAINER : nom de votre conteneur.
    • IMAGE_URL : référence à l'image de conteneur, par exemple us-docker.pkg.dev/cloudrun/container/hello:latest. Si vous utilisez Artifact Registry, le dépôt REPO_NAME doit déjà être créé. L'URL est au format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.

  3. Créez ou mettez à jour le service à l'aide de la commande suivante :

    gcloud run services replace service.yaml

    La commande gcloud run services replace utilise par défaut le fichier service.yaml s'il est présent.

Les bacs à sable partagent le processeur et la mémoire alloués au conteneur hôte. Assurez-vous que les limites de processeur et de mémoire de votre conteneur principal sont suffisantes pour votre application et pour les bacs à sable actifs que vous exécutez en même temps.

Désactiver les bacs à sable

Pour désactiver la possibilité de lancer un bac à sable dans votre service, utilisez Google Cloud CLI ou une configuration YAML :

gcloud

Mettez à jour le service à l'aide de l'indicateur --no-sandbox-launcher en exécutant la commande suivante :

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

Remplacez SERVICE par le nom du service.

YAML

  1. Si vous créez un service, ignorez cette étape. Si vous mettez à jour un service existant, téléchargez sa configuration YAML :

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

  2. Mettez à jour le fichier YAML de votre service pour supprimer l'attribut sandboxLauncher dans la configuration de votre conteneur :

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

    Remplacez les éléments suivants :

    • SERVICE : nom de votre service Cloud Run.
    • CONTAINER : nom de votre conteneur.
    • IMAGE_URL : référence à l'image de conteneur, par exemple us-docker.pkg.dev/cloudrun/container/hello:latest. Si vous utilisez Artifact Registry, le dépôt REPO_NAME doit déjà être créé. L'URL est au format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.

  3. Créez ou mettez à jour le service à l'aide de la commande suivante :

    gcloud run services replace service.yaml

    La commande gcloud run services replace utilise par défaut le fichier service.yaml s'il est présent.

Lancer des bacs à sable

Une fois les bacs à sable activés, vous pouvez les lancer depuis votre environnement d'exécution de conteneur. Le fichier binaire du bac à sable se trouve à l'emplacement /usr/local/gcp/bin/sandbox.

Vous pouvez exécuter le fichier binaire en référençant son chemin d'accès absolu dans votre code source. Par exemple, pour imprimer Hello dans votre bac à sable isolé, choisissez l'une des options suivantes :

Node.js

Pour exécuter la commande sandbox à partir d'une application Node.js, incluez le code suivant :

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

Python

Pour exécuter la commande de bac à sable à partir d'une application Python, incluez le code suivant :

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

Pour exécuter la commande sandbox à partir d'une application Go, incluez le code suivant :

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

CLI Sandbox

Pour exécuter la commande sandbox directement à partir de la ligne de commande, exécutez la commande suivante :

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

Les exemples de ce guide utilisent la commande sandbox au lieu de son chemin d'accès absolu /usr/local/gcp/bin/sandbox.

Pour afficher la liste complète des commandes disponibles, exécutez la commande /usr/local/gcp/bin/sandbox -h.

Utiliser les fonctionnalités de ligne de commande du bac à sable

L'outil de ligne de commande sandbox contient des commandes permettant d'exécuter, de configurer et de gérer des bacs à sable.

Exécuter une commande dans votre bac à sable

Vous pouvez exécuter une instruction dans un nouveau bac à sable éphémère à l'aide de la commande sandbox do. La commande sandbox do exécute les tâches suivantes :

  1. Crée un environnement de bac à sable (sandbox run).
  2. Exécute la commande que vous spécifiez (sandbox exec).
  3. Supprime le bac à sable après l'exécution (sandbox delete).

Par exemple, pour effectuer un calcul mathématique dans le bac à sable, exécutez les extraits de code suivants pour la langue de votre choix. Assurez-vous que toutes les commandes ou tous les outils que vous exécutez, tels que python3, sont installés dans votre image de conteneur :

Node.js

Pour exécuter la commande sandbox à partir d'une application Node.js :

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

Python

Pour exécuter la commande de bac à sable à partir d'une application Python :

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

Pour exécuter la commande sandbox à partir d'une application Go :

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

CLI Sandbox

Pour exécuter la commande sandbox directement depuis la ligne de commande :

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

Si vous exécutez une commande par son nom sans son chemin d'accès absolu, par exemple python3 au lieu de /usr/bin/python3, configurez explicitement la variable d'environnement PATH dans le bac à sable à l'aide du flag --env.

Conserver les données entre différentes exécutions

Les bacs à sable sont éphémères par défaut. Pour conserver les données lors de différentes exécutions de bac à sable au sein de la même instance Cloud Run, vous pouvez importer et exporter l'état du système de fichiers de l'espace de travail à l'aide de fichiers d'archive tar standards. Vous pouvez également configurer des montages de liaison pour partager directement des répertoires entre le conteneur hôte et les environnements de bac à sable.

Utilisez les indicateurs suivants lorsque vous exécutez la commande sandbox do :

  • --export-tar : capture les fichiers de superposition modifiés dans un fichier d'archive tar une fois l'opération terminée.
  • --import-tar : extrait les fichiers d'un fichier d'archive tar dans le bac à sable avant l'exécution.
  • --sync-tar : effectue une synchronisation bidirectionnelle en important les données avant l'exécution et en les exportant une fois l'exécution terminée.

Par exemple, pour transmettre des données entre deux appels de bac à sable à l'aide de fichiers d'archive, exécutez les commandes suivantes :

  1. Écrivez des données dans un bac à sable et exportez l'état vers un fichier d'archive :

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

  2. Importez le fichier d'archive dans un appel ultérieur pour récupérer les données :

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

Vous pouvez également utiliser --sync-tar=/tmp/work.tar pour importer automatiquement l'état d'archivage existant et exporter les nouvelles modifications en une seule commande. Lorsqu'un processus de bac à sable se termine, Cloud Run supprime définitivement les fichiers de superposition éphémères qui n'ont pas été exportés vers un fichier d'archive.

Exécuter une commande en arrière-plan

Pour exécuter des processus de longue durée, des navigateurs sans interface graphique ou des serveurs en arrière-plan, tels qu'une boucle d'agent en arrière-plan qui écoute en continu les requêtes entrantes, utilisez l'indicateur --detach.

Par exemple, exécutez la commande suivante pour démarrer un bac à sable détaché avec un programme inactif ou en arrière-plan :

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

Vous pouvez utiliser l'indicateur detach pour réutiliser le même bac à sable pour plusieurs tests. Pour interagir avec un bac à sable détaché en cours d'exécution ou exécuter des commandes supplémentaires à l'intérieur, utilisez la commande sandbox exec et ciblez votre bac à sable par son nom.

Par exemple, pour exécuter une commande de test dans votre bac à sable en arrière-plan my-web-server existant, exécutez la commande suivante :

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

Configurer les variables d'environnement

Configurez les variables d'environnement dans les bacs à sable comme vous le feriez pour n'importe quel autre conteneur. Les bacs à sable n'héritent pas des variables d'environnement du conteneur hôte. Vous devez les fournir explicitement à l'aide de l'indicateur --env lorsque vous exécutez la commande sandbox.

Par exemple, pour transmettre une variable de configuration à un bac à sable, exécutez la commande suivante :

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

Évitez de transmettre des secrets à l'aide du flag env, car ils peuvent être visibles par les processus du bac à sable.

Créer des instantanés du système de fichiers

Déployez un bac à sable nommé en arrière-plan pour gérer les tâches continues telles que les serveurs Web ou les workflows d'agent de longue durée, exécutez des commandes de manière dynamique sur le bac à sable et capturez l'état modifié du système de fichiers dans un fichier d'archive tar.

Par exemple, pour déployer un bac à sable en arrière-plan, écrire un fichier dans sa superposition et créer un instantané de son état pour vérifier que les données ont été capturées, exécutez les commandes suivantes :

  1. Déployez un bac à sable nommé en arrière-plan avec l'accès en écriture activé, en créant un fichier dans son espace de travail :

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

  2. Créez un instantané du système de fichiers modifié du bac à sable en cours d'exécution à l'aide de la commande sandbox tar :

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

  3. Extrayez et vérifiez que le fichier d'archive de l'instantané contient les données écrites dans le bac à sable :

    tar -xvf /tmp/foo.tar

    Les résultats suivants doivent s'afficher :

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

Configurer la mise en réseau

Par défaut, tout le trafic sortant du bac à sable est bloqué. Pour autoriser l'accès au réseau sortant, utilisez l'option --allow-egress :

Par exemple, pour extraire des données d'un point de terminaison externe, exécutez la commande suivante :

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

Cette commande renvoie le code d'état HTTP standard 200, qui indique que la connexion a réussi.

Accéder au système de fichiers

Par défaut, les processus que vous exécutez dans le bac à sable ont un accès en lecture seule au système de fichiers racine du conteneur hôte. Vous pouvez utiliser l'option --write pour activer l'écriture dans une superposition de système de fichiers temporaire (tmpfs). Toutefois, les écritures seront perdues lorsque le bac à sable sera supprimé. Pour activer l'écriture persistante dans le conteneur hôte, vous pouvez configurer des montages de liaison.

Accès en lecture seule par défaut

Dans le bac à sable, les processus peuvent lire les fichiers du conteneur hôte, mais ils ne peuvent pas écrire dans le système de fichiers racine.

Les exemples suivants supposent que vous exécutez les commandes à partir du répertoire racine (/) de votre conteneur hôte.

Pour vérifier l'accès en lecture seule par défaut, exécutez les commandes suivantes :

  1. Créez un script Python sur le conteneur hôte :

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

  2. Vérifiez que le fichier existe en local :

    cat /tmp/my-scripts/task.py

  3. Exécutez le fichier dans votre bac à sable :

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

    Cette commande renvoie hi, ce qui confirme que le bac à sable dispose d'un accès en lecture.

    Si vous tentez d'écrire des données directement dans le système de fichiers racine du bac à sable sans configuration supplémentaire, l'exécution échoue. Par exemple, toute tentative d'écriture dans /tmp à l'intérieur du bac à sable par défaut renvoie une erreur de système de fichiers en lecture seule :

    Exécutez la commande suivante pour écrire dans le système de fichiers racine :

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

    La commande échoue et affiche l'erreur suivante :

    /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

Partager des données à l'aide de montages de liaison

Pour autoriser les processus à l'intérieur du bac à sable à écrire des données persistantes, associez un volume partagé à l'aide de l'indicateur --mount :

  1. Créez un répertoire de volume partagé sur le conteneur hôte et remplissez-le avec un fichier initial :

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

  2. Exécutez le bac à sable pour lire le fichier à partir du chemin de montage :

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

    Cette commande renvoie read.

  3. Exécutez le bac à sable pour réécrire de nouvelles données sur l'hôte depuis le montage :

    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. Vérifiez sur le conteneur hôte que le fichier a bien été modifié par le bac à sable :

    cat /tmp/my-volume/readwrite.txt

    Cette commande renvoie write.

Configurer des montages en lecture seule

Pour accorder au bac à sable l'accès à un répertoire hôte tout en l'empêchant explicitement de modifier des fichiers, ajoutez l'attribut readonly à la spécification de montage.

Par exemple, exécutez la commande suivante pour tester les restrictions d'écriture sur un montage par liaison en lecture seule :

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"

La tentative d'écriture échoue avec l'erreur suivante :

/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

Afficher les journaux

Cloud Run capture automatiquement les événements du cycle de vie du bac à sable, tels que les démarrages et les sorties d'exécution, dans Cloud Logging.

L'CLI sandbox écrit la sortie standard (stdout) et l'erreur standard (stderr) des commandes mises en bac à sable directement dans les flux standards du processus d'appel. Pour afficher ces journaux dans Cloud Logging, routez les flux vers la sortie et l'erreur standards de votre conteneur :

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

Étapes suivantes