Modèles de nettoyage

Ces exemples utilisent un jeton d’accès à l’API CoreWeave défini dans CWSANDBOX_API_KEY. Pour l’authentification par clé API Forge, consultez Premiers pas. Pour les exigences relatives à CKS, consultez Modes de placement. Ce guide présente des stratégies de gestion des ressources et de nettoyage pour les bacs à sable. 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.

Nettoyage automatique

Le nettoyage automatique lie la durée de vie d’une sandbox à une construction Python (un gestionnaire de contexte, 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 continue de s’exécuter après la fin de votre script, jusqu’à ce que sa commande principale se termine, que vous l’arrêtiez ou que sa durée de vie maximale soit atteinte.

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 bacs à sable à la sortie du contexte :

from cwsandbox import Sandbox

with Sandbox.run() as sandbox:
    result = sandbox.exec(["echo", "hello"]).result()
# sandbox.stop() est appelé automatiquement

Les sessions nettoient tous leurs bacs à sable :

import cwsandbox
from cwsandbox import SandboxDefaults

with cwsandbox.Session(SandboxDefaults(container_image="python:3.11")) 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 sandboxes des sessions enregistrées lorsque le processus se termine. Les sandboxes 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 sandboxes des sessions enregistrées
Ctrl+C (`SIGINT`)	Le handler de signal arrête les sandboxes des sessions enregistrées
`SIGTERM`	Le handler de signal arrête les sandboxes 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 c’est alors à votre application d’arrêter les sandboxes à 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()

sandbox = Sandbox.run()
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()

Session close()

from cwsandbox import SandboxDefaults

session = cwsandbox.Session(SandboxDefaults(container_image="python:3.11"))
sandbox = session.sandbox()
# ...
session.close().result()  # Arrête tous les bacs à sable

Nettoyage par lot

from cwsandbox import results

sandboxes = [Sandbox.run() 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

Pour les bacs à sable créés dans des sessions et des gestionnaires de contexte, le nettoyage automatique du SDK évite la plupart des bacs à sable orphelins. Ces bacs à sable 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. Utilisez des étiquettes pour pouvoir retrouver plus tard les éventuels bacs à sable orphelins.

from cwsandbox import Sandbox, SandboxDefaults

# Ajouter des étiquettes à la création
defaults = SandboxDefaults(
    container_image="python:3.11",
    tags=("my-project", "batch-job-123"),
)

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

Bonnes pratiques d’étiquetage :

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 bacs à sable orphelins

Filtrez les bacs à sable par tag pour trouver ceux issus de runs précédents :

from cwsandbox import Sandbox

orphans = Sandbox.list(tags=["my-project"]).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 bacs à sable nouvellement créés. session.list() ajoute les étiquettes par défaut de la session à votre filtre et ne trouve donc que les bacs à sable qui les portent. Pour effectuer une recherche sans les étiquettes de la session, utilisez Sandbox.list() et adoptez chacun des résultats, comme indiqué dans le guide des sessions :

import cwsandbox
from cwsandbox import SandboxDefaults

with cwsandbox.Session(SandboxDefaults(container_image="python:3.11")) 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

Supprimer par ID

Si vous connaissez déjà l’ID d’une sandbox, vous pouvez la supprimer directement, sans avoir à la lister ni à l’adopter au préalable :

from cwsandbox import Sandbox

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

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

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 bacs à sable orphelins

Adoption par une session

Supprimer par ID

​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 bacs à sable orphelins

​Adoption par une session

​Supprimer par ID

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 bacs à sable orphelins

Adoption par une session

Supprimer par ID