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 de ligne de commande pour exécuter du code non approuvé écrit dans n'importe quel langage, dans un environnement de bac à sable hautement optimisé, isolé du reste de votre conteneur.

Les agents d'IA peuvent exploiter les bacs à sable pour exécuter en toute sécurité 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 délais de création par rapport à la création d'une ressource Cloud Run pour chaque tâche. Cette efficacité permet de s'assurer 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 Google Cloud métadonnées. Tous 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 les droits sudo en tant qu' utilisateur non root, ce qui vous permet d'installer des outils à l'aide de gestionnaires de packages tels qu' 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'exécution terminée, vous pouvez utiliser des répertoires persistants ou des instantanés pour enregistrer des espaces de travail spécifiques ou mapper des données à un bucket Cloud Storage.

Avant de commencer

  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. Installez et initialisez la gcloud CLI.
  4. Déployez une ressource Cloud Run, telle qu'un service de deuxième génération , job, pool de nœuds de calcul ou une instance.

Activer les bacs à sable

Pour utiliser les bacs à sable, vous devez d'abord les activer sur votre ressource Cloud Run à l'aide de l'option --sandbox-launcher ou de l'attribut YAML sandboxLauncher. Pour obtenir des instructions de configuration détaillées, choisissez l'un des types de ressources suivants :

Lancer les bacs à sable

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

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

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

Node.js

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

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

Python

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

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

Go

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

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

CLI du bac à sable

Pour exécuter la commande du bac à sable directement à partir de la ligne de commande, exécutez la commande suivante :

sandbox do -- /bin/echo "Hello"

Pour afficher la liste complète des commandes disponibles, exécutez la sandbox -h commande.

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 les 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 effectue les tâches suivantes :

  1. Lance un environnement de bac à sable (sandbox run).
  2. Exécute la commande que vous spécifiez (sandbox exec).
  3. Supprime le bac à sable une fois l'exécution réussie (sandbox delete).

Par exemple, pour effectuer un calcul mathématique dans le bac à sable, exécutez les extraits de code suivants pour le langage 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 du bac à sable à 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 du 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 du bac à sable à partir d'une application Go :

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

CLI du bac à sable

Pour exécuter la commande du bac à sable directement à partir de 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 de l'option --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 entre différentes exécutions de bac à sable dans 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 installations de liaison pour partager des répertoires directement entre le conteneur hôte et les environnements de bac à sable.

Utilisez les options suivantes 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'exécution 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 avant l'exécution et en 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 lors d'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 importer automatiquement l'état d'archive existant et exporter les nouvelles modifications en une seule commande à l'aide de --sync-tar=/tmp/work.tar. 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 permanence les requêtes entrantes, utilisez l'option --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'option 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 y exécuter des commandes supplémentaires, 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

Configure variables d'environnement sur 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'option --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 de l'option 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 sur le bac à sable de manière dynamique et capturez l'état modifié de son 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 prendre 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 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, indiquant 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 disposent d'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 installations de liaison.

Accès en lecture seule par défaut

Dans le bac à sable, les processus peuvent lire des fichiers à partir 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 des 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 localement :

    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, si vous tentez d'écrire dans /tmp dans le bac à sable par défaut, une erreur de système de fichiers en lecture seule est renvoyée :

    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 avec 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 d'installations de liaison

Pour autoriser les processus dans le bac à sable à écrire des données persistantes, associez un volume partagé à l'aide de l'option --mount :

  1. Créez un répertoire de volume partagé sur le conteneur hôte et initialisez-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 d'installation de liaison :

    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 à partir de l'installation :

    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 bac à sable a bien modifié le fichier :

    cat /tmp/my-volume/readwrite.txt

    Cette commande renvoie write.

Configurer des installations 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 d'installation.

Par exemple, exécutez la commande suivante pour tester les restrictions d'écriture sur une installation de 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.

La 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 appelant. Pour afficher ces journaux dans Cloud Logging, acheminez 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()

Étape suivante