Modèles de nettoyage

Ce guide présente des stratégies de gestion des ressources et de nettoyage pour les sandboxes. Un nettoyage fiable empêche que des sandboxes restent orphelines une fois le script terminé, ce qui permet de maîtriser les coûts et d’éviter toute consommation involontaire de ressources de calcul. Les modèles présentés ici s’appliquent aux scripts qui créent une ou plusieurs sandboxes, avec ou sans session explicite.

Choisir l’authentification

Ces exemples s’exécutent sur une capacité sans serveur, sauf si une section précise CKS. Choisissez l’identifiant d’authentification du compte propriétaire de vos Sandbox. Pour obtenir une clé ou un jeton, consultez Choisir et obtenir des identifiants d’authentification. Exécutez les commandes d’installation dans un environnement virtuel Python actif. Enregistrez le code Python de l’onglet correspondant à votre identifiant d’authentification sous le nom sandbox_auth.py, dans le même répertoire que les scripts Python que vous exécutez depuis cette page. Ce fichier enregistre le mode d’authentification choisi, et non votre identifiant d’authentification. Les exemples importent AUTH depuis ce fichier et le transmettent explicitement à chaque nouvelle sandbox ou session.

Clé API Forge
Jeton d’accès à l’API CoreWeave

Utilisez votre clé API Forge avec la stratégie d’authentification W&B du SDK :

uv pip install 'cwsandbox[wandb]>=1.14.2'
export WANDB_API_KEY="[WANDB-API-KEY]"

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.WANDB

Utilisez le jeton de votre organisation CoreWeave :

uv pip install 'cwsandbox>=1.14.2'
export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.COREWEAVE_API_KEY

Pour un placement sur CKS, choisissez le jeton CoreWeave, activez un exécuteur et définissez placement_mode="cks" lors de la création de la sandbox ou dans SandboxDefaults. Une session créée avec auth=AUTH authentifie également les Sandbox qui lui appartiennent. Utilisez le même identifiant d’authentification pour vous reconnecter à vos Sandbox, les lister ou les nettoyer.

Nettoyage automatique

Le nettoyage automatique lie la durée de vie d’une sandbox à un gestionnaire de contexte Python ou à une session que le SDK ferme à la fin du processus. Le SDK libère ainsi les ressources sans que vous ayez à appeler explicitement stop(). Une sandbox démarrée avec Sandbox.run() en dehors d’une session ou d’un gestionnaire de contexte peut continuer de s’exécuter après la fin de votre script. Elle s’arrête lorsque sa commande principale se termine avec succès (statut de sortie 0), lorsque vous l’arrêtez ou lorsque sa durée de vie maximale est atteinte. Une sortie avec un code non nul peut déclencher des redémarrages automatiques du conteneur. La sandbox passe en échec si elle atteint la limite de redémarrages. Voir Durée de vie de la commande principale.

Gestionnaires de contexte (recommandé)

Les gestionnaires de contexte constituent l’approche recommandée, car ils garantissent le nettoyage même si le code qu’ils encadrent lève une exception. Le SDK arrête les Sandbox à la sortie du contexte :

from sandbox_auth import AUTH
from cwsandbox import Sandbox

with Sandbox.run(resources={"cpu": "1", "memory": "1Gi"}, auth=AUTH) as sandbox:
    result = sandbox.exec(["echo", "hello"]).result()
# sandbox.stop() est appelé automatiquement

Les sessions nettoient tous leurs Sandbox :

from sandbox_auth import AUTH
import cwsandbox
from cwsandbox import SandboxDefaults

with cwsandbox.Session(SandboxDefaults(
    container_image="python:3.11",
    resources={"cpu": "1", "memory": "1Gi"},
), auth=AUTH) as session:
    sb1 = session.sandbox()
    sb2 = session.sandbox()
# Les deux bacs à sable sont arrêtés automatiquement

Handlers de nettoyage globaux

Le SDK enregistre des handlers de nettoyage qui arrêtent les Sandbox des sessions enregistrées lorsque le processus se termine. Les Sandbox autonomes, créées en dehors d’une session ou d’un gestionnaire de contexte, doivent être nettoyées explicitement :

Scénario	Comportement
Fin normale du script	Le handler `atexit` arrête les Sandbox des sessions enregistrées
Ctrl+C (`SIGINT`)	Le handler de signal arrête les Sandbox des sessions enregistrées
`SIGTERM`	Le handler de signal arrête les Sandbox des sessions enregistrées
Second Ctrl+C	Sortie forcée (évite un arrêt qui ne répond plus)

Le SDK installe ces handlers lorsque votre code crée sa première sandbox. Les handlers SIGINT et SIGTERM ne sont installés que depuis le thread principal de Python. Si votre application gère ses propres signaux, appelez cwsandbox.disable_signal_handlers() ou définissez CWSANDBOX_DISABLE_SIGNAL_HANDLERS=1 avant de créer la première sandbox. Le handler atexit s’exécute toujours, mais votre application doit arrêter elle-même les Sandbox à la réception d’un signal.

Nettoyage manuel

Utilisez le nettoyage manuel lorsque vous avez besoin de contrôler explicitement le moment où une sandbox ou une session est libérée. Le nettoyage manuel vous permet de transmettre des options d’arrêt ou de coordonner le nettoyage au sein d’un code qui s’exécute longtemps.

Sandbox stop()

L’exemple suivant arrête une sandbox individuelle et présente les paramètres d’arrêt facultatifs :

from sandbox_auth import AUTH
from cwsandbox import Sandbox

sandbox = Sandbox.run(resources={"cpu": "1", "memory": "1Gi"}, auth=AUTH)
result = sandbox.exec(["echo", "hello"]).result()
sandbox.stop().result()

# Avec options
sandbox.stop(graceful_shutdown_seconds=30.0).result()
sandbox.stop(snapshot_on_stop=True).result()
sandbox.stop(missing_ok=True).result()  # Ignorer si déjà supprimée

Session close()

Lorsque vous fermez une session, celle-ci arrête tous les Sandbox qui lui appartiennent :

from sandbox_auth import AUTH
from cwsandbox import SandboxDefaults

session = cwsandbox.Session(SandboxDefaults(
    container_image="python:3.11",
    resources={"cpu": "1", "memory": "1Gi"},
), auth=AUTH)
sandbox = session.sandbox()
# ...
session.close().result()  # Arrête tous les bacs à sable

Nettoyage par lot

L’exemple suivant arrête plusieurs Sandbox en parallèle :

from sandbox_auth import AUTH
from cwsandbox import results

sandboxes = [
    Sandbox.run(resources={"cpu": "1", "memory": "1Gi"}, auth=AUTH)
    for _ in range(5)
]
# ... utiliser les sandboxes ...
results([sb.stop() for sb in sandboxes])  # Arrêter toutes les sandboxes en parallèle

Gestion des orphelins

Les orphelins sont des bacs à sable restés en cours d’exécution par inadvertance après la fin du processus qui les a créés. Une sandbox autonome que vous laissez délibérément s’exécuter n’est pas un orphelin, mais elle le devient si vous en perdez la trace. Les sections suivantes expliquent comment faciliter le repérage des orphelins, comment les trouver à l’aide d’une requête et comment les réintégrer dans le nettoyage géré.

Étiquetage pour la découverte

Utilisez des tags pour pouvoir retrouver plus tard les éventuels Sandbox orphelins. Pour les Sandbox créés dans des sessions et des gestionnaires de contexte, le nettoyage automatique du SDK évite la plupart des Sandbox orphelins. Ces Sandbox peuvent toutefois continuer à s’exécuter après un arrêt forcé (kill -9) ou une défaillance réseau. Les handlers de nettoyage n’arrêtent jamais un sandbox autonome ; il devient donc orphelin si vous oubliez de l’arrêter.

from sandbox_auth import AUTH
from cwsandbox import Sandbox, SandboxDefaults

# Ajouter des étiquettes à la création
defaults = SandboxDefaults(
    container_image="python:3.11",
    tags=("my-project", "batch-job-123"),
    resources={"cpu": "1", "memory": "1Gi"},
)

with Sandbox.run(defaults=defaults, auth=AUTH) as sandbox:
    result = sandbox.exec(["echo", "hello"]).result()

Utilisez les tags suivants pour pouvoir retrouver les Sandbox :

Nom du projet ou de l’application (my-project)
Identifiant de la tâche ou du run (batch-job-123, run-2024-01-15)
Environnement (dev, staging, prod)

Trouver les sandboxes orphelins

Filtrez les sandboxes par tag pour trouver ceux issus de runs précédents :

from sandbox_auth import AUTH
from cwsandbox import Sandbox

orphans = Sandbox.list(tags=["my-project"], auth=AUTH).result()
for sandbox in orphans:
    sandbox.stop().result()

Adoption par une session

Adopter un sandbox orphelin le rattache à une session, qui gère alors sa durée de vie. L’orphelin bénéficie dès lors des mêmes garanties de nettoyage automatique que les Sandbox nouvellement créés. session.list() ajoute les tags par défaut de la session à votre filtre et ne trouve donc que les Sandbox qui les portent. Pour effectuer une recherche sans les tags de la session, utilisez Sandbox.list() et adoptez chacun des résultats, comme indiqué dans le guide des sessions :

from sandbox_auth import AUTH
import cwsandbox
from cwsandbox import SandboxDefaults

with cwsandbox.Session(SandboxDefaults(
    container_image="python:3.11",
    resources={"cpu": "1", "memory": "1Gi"},
), auth=AUTH) as session:
    orphans = session.list(tags=["my-project"]).result()
    for sandbox in orphans:
        session.adopt(sandbox)
# Tous les bacs à sable adoptés sont nettoyés en même temps que la session

Arrêter par ID

Pour arrêter une sandbox dont vous avez enregistré l’ID lors d’un run précédent, reconnectez-vous avec le même identifiant d’authentification. Remplacez [SANDBOX-ID] par l’ID de la sandbox :

from sandbox_auth import AUTH
from cwsandbox import Sandbox

sandbox = Sandbox.from_id("[SANDBOX-ID]", auth=AUTH).result()
sandbox.stop(missing_ok=True).result()

Si la sandbox disparaît avant la requête d’arrêt, l’option missing_ok=True empêche la levée de SandboxNotFoundError. En revanche, elle n’a aucun effet sur l’échec d’une recherche via Sandbox.from_id() : si la sandbox n’existe déjà plus, cet appel lève quand même SandboxNotFoundError.

Supprimer par ID

Pour utiliser des options telles que graceful_shutdown_seconds ou snapshot_on_stop, appelez stop() sur une instance de sandbox. Sandbox.delete() supprime la sandbox directement à partir de son ID, sans créer d’instance. Si vous connaissez déjà l’ID d’une sandbox, vous pouvez la supprimer sans avoir à la lister ni à l’adopter au préalable :

from sandbox_auth import AUTH
from cwsandbox import Sandbox

Sandbox.delete("sandbox-abc123", auth=AUTH).result()
Sandbox.delete("sandbox-abc123", missing_ok=True, auth=AUTH).result()  # Ignorer si elle n’existe plus

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

Choisir l’authentification

Nettoyage automatique

Gestionnaires de contexte (recommandé)

Handlers de nettoyage globaux

Nettoyage manuel

Sandbox stop()

Session close()

Nettoyage par lot

Gestion des orphelins

Étiquetage pour la découverte

Trouver les sandboxes orphelins

Adoption par une session

Arrêter par ID

Supprimer par ID

​Choisir l’authentification

​Nettoyage automatique

​Gestionnaires de contexte (recommandé)

​Handlers de nettoyage globaux

​Nettoyage manuel

​Sandbox stop()

​Session close()

​Nettoyage par lot

​Gestion des orphelins

​Étiquetage pour la découverte

​Trouver les sandboxes orphelins

​Adoption par une session

​Arrêter par ID

​Supprimer par ID

Choisir l’authentification

Nettoyage automatique

Gestionnaires de contexte (recommandé)

Handlers de nettoyage globaux

Nettoyage manuel

Sandbox stop()

Session close()

Nettoyage par lot

Gestion des orphelins

Étiquetage pour la découverte

Trouver les sandboxes orphelins

Adoption par une session

Arrêter par ID

Supprimer par ID