Le client TypeScript prend en charge les montages d’instantanés, les restaurations, les instantanés en cours d’exécution et la gestion des instantanés, mais pas la création d’instantanés à l’arrêt.
Choisir l’authentification
Ces exemples s’exécutent sur une capacité sans serveur, sauf si une section indique CoreWeave Kubernetes Service (CKS). Choisissez l’identifiant d’authentification du compte propriétaire de vos Sandbox. Consultez Choisir et obtenir des identifiants pour obtenir une clé ou un jeton. Enregistrez la configuration correspondant à votre langage dans le même répertoire que les scripts que vous exécutez depuis cette page. Les exemples Python importentAUTH depuis sandbox_auth.py. Les exemples TypeScript importent client depuis sandbox-client.mts. Ces fichiers sélectionnent l’authentification sans stocker votre identifiant d’authentification. Pour Python, utilisez un environnement virtuel actif. Pour TypeScript, installez d’abord le client avec npm install @coreweave/cwsandbox@1.0.0.
- Clé API Forge
- Jeton d’accès à l’API CoreWeave
Utilisez votre clé API Forge avec l’intégration
wandb du SDK. Remplacez [WANDB-API-KEY] par votre clé API :- Python
- TypeScript
sandbox_auth.py
placement_mode="cks" lors de la création du Sandbox ou dans SandboxDefaults. En TypeScript, choisissez le jeton CoreWeave et définissez un tableau runnerIds non vide pour sélectionner CKS. La création d’une session Python avec auth=AUTH authentifie également les Sandbox qui lui appartiennent. Conservez le même identifiant d’authentification pour vous reconnecter à vos Sandbox, les lister ou les nettoyer.
Pour les exemples d’API HTTP, exécutez les commandes Bash de l’onglet correspondant à votre identifiant d’authentification dans le même shell que les requêtes. Le tableau sandbox_headers fournit l’en-tête d’authentification sélectionné. Les exemples de création via HTTP utilisent un placement sans serveur.
Fonctionnement
Une Sandbox avec FSS monte un système de fichiers temporaire accessible en écriture à l’emplacement de votre choix. L’exécuteur s’appuie sur unEmptyDir pour ce montage, et non sur un montage direct du stockage d’objets. Les opérations d’instantané et de restauration copient une archive tar entre ce système de fichiers local et un bucket de stockage d’objets limité à l’organisation.
Chaque instantané est une ressource FileSystemSnapshot identifiée par un fileSystemSnapshotId attribué par le serveur. Les instantanés se caractérisent par trois propriétés :
- Immuable : la création d’un instantané écrit une seule archive. La restauration d’un instantané ne modifie jamais l’instantané source ; une restauration ultérieure retrouve donc toujours les octets d’origine.
- Limité à l’organisation : vous ne pouvez restaurer que les instantanés créés dans votre propre organisation. Un membre de votre équipe disposant d’un accès aux Sandbox dans la même organisation peut restaurer votre instantané avec ses propres identifiants d’authentification. Un ID d’instantané provenant d’une autre organisation est considéré comme introuvable.
- Cycle de vie indépendant : les instantanés sont gérés séparément des Sandbox. La suppression d’une Sandbox ne supprime pas ses instantanés, et la suppression d’un instantané n’a aucune incidence sur les Sandbox déjà lancées à partir de celui-ci.
Démarrer un sandbox avec un montage d’instantané
Un sandbox peut démarrer à partir de l’une de ces deux sources de système de fichiers : un système de fichiers temporaire, neuf et vide, ou la restauration d’un instantané existant.Système de fichiers temporaire vierge
Un système de fichiers temporaire vierge est vide au démarrage et peut faire l’objet d’un instantané par la suite. Utilisez-le pour les flux de travail qui nécessitent un état local accessible en écriture pendant l’exécution.- Python
- TypeScript
- API HTTP
Restaurer à partir d’un instantané
Une restauration initialise le système de fichiers à partir d’un instantané existant. Indiquez l’ID de l’instantané dans la source d’instantané du point de montage.- Python
- TypeScript
- API HTTP
READY pour pouvoir être restauré. La restauration d’un instantané encore à l’état CREATING échoue. Consultez Statut et échecs des instantanés.
Prévoir le temps de restauration
Lors de la restauration d’un instantané, son archive est copiée puis extraite avant que la sandbox puisse exécuter votre application. La restauration d’instantanés de modèles volumineux peut prendre plusieurs minutes. Le temps de démarrage dépend des facteurs suivants :- Taille de l’archive
- Nombre de fichiers
- CPU disponible
- Stockage local
- Débit réseau
- Opérations de démarrage de l’image
CREATING ne permet pas, à lui seul, de distinguer l’attente de l’ordonnancement de la restauration des fichiers. Avant de supprimer un lancement lent, vérifiez le champ status_reason de la sandbox et conservez son ID pour l’assistance. Un délai fixe permet de borner votre attente, mais le temps écoulé ne suffit pas à établir qu’une restauration a échoué.
Prendre un instantané
Vous pouvez capturer un instantané de deux façons : à l’arrêt, lorsqu’une sandbox s’éteint, ou en cours d’exécution, depuis une sandbox active.Instantané à l’arrêt
Pour conserver le système de fichiers d’une sandbox lors de son arrêt, arrêtez-la en activant l’instantané à l’arrêt. C’est la méthode à suivre pour suspendre puis reprendre une sandbox : arrêtez-la avec un instantané, puis démarrez ultérieurement une nouvelle sandbox qui le restaure.- Python
- TypeScript
- API HTTP
Instantané en cours d’exécution
Un instantané en cours d’exécution capture une sandbox active sans l’arrêter. La sandbox continue de s’exécuter pendant et après la capture. La capture parcourt le système de fichiers actif et n’est pas atomique : les écritures effectuées pendant la capture risquent donc de ne pas être capturées de manière cohérente. Si vous avez besoin d’un état cohérent, suspendez les écritures de l’application pendant la capture ou créez un point de contrôle applicatif au préalable.- Python
- TypeScript
- API HTTP
Par défaut,
snapshot() attend que l’instantané soit READY, puis renvoie son ID.Créer une branche à partir d’un instantané
Un même instantané peut être restauré dans plusieurs sandbox. Comme chaque instantané est immuable, les sandbox restaurées démarrent à partir d’octets identiques, puis divergent au fil de leurs écritures.- Créez un instantané
READY, soit avec un instantané à l’arrêt, soit avec un instantané en cours d’exécution. - Démarrez la sandbox A en définissant
fileSystemSnapshotIdsur cet instantané. - Démarrez la sandbox B avec le même
fileSystemSnapshotId. - Les écritures effectuées dans la sandbox A et dans la sandbox B divergent indépendamment les unes des autres. L’instantané source n’est pas modifié : une restauration ultérieure à partir du même ID retrouve donc l’instantané original, et non les écritures de l’une ou l’autre branche.
- Python
- TypeScript
Gérer les instantanés
Listez, récupérez et supprimez les instantanés indépendamment des Sandbox qui les ont créés.- Python
- TypeScript
- API HTTP
list_snapshots(), get_snapshot() et delete_snapshot() acceptent également un objet AuthHeaders via le paramètre auth.
Statut des instantanés et échecs
Les instantanés sont créés de manière asynchrone. Une requête d’instantané peut réussir et renvoyer unfileSystemSnapshotId alors que l’archive est encore en cours d’écriture, puis l’instantané peut échouer par la suite. Cela se produit le plus souvent lorsque waitForReady vaut false, ou lorsque le délai d’expiration côté client est atteint alors que l’exécuteur est encore en train d’archiver.
Pour suivre la progression via l’API HTTP, récupérez l’instantané et consultez les champs suivants :
status: l’état du cycle de vie. Les valeurs finales sontFILE_SYSTEM_SNAPSHOT_STATUS_READYetFILE_SYSTEM_SNAPSHOT_STATUS_FAILED.statusReason: renseigné lorsquestatusvautFILE_SYSTEM_SNAPSHOT_STATUS_FAILED, pour indiquer la cause de l’échec.
state et stateReason de l’enregistrement de l’instantané. Les valeurs d’état correspondantes sont "ready" et "failed".
Interrogez GetFileSystemSnapshot jusqu’à ce que l’instantané soit prêt avant de le restaurer. Les méthodes snapshot() et get_snapshot() du client Python se chargent de cette interrogation pour vous lorsque vous attendez le résultat. La méthode snapshot() du client TypeScript attend que state vaille "ready" et lève une exception si l’instantané échoue.
Récupérer après l’échec d’une requête d’instantané
Pendant la récupération après l’échec d’un instantané en cours d’exécution, laissez la sandbox source en fonctionnement. L’échec d’un appel de procédure à distance (RPC) d’instantané ne supprime pas en soi la sandbox ni son point de montage. En revanche, si vous quittez un gestionnaire de contexte de sandbox Python ou exécutez du code de démontage, la sandbox peut s’arrêter. Les données qui ne figurent pas encore dans un instantané prêt peuvent alors être perdues. Traitez l’échec avant que ce nettoyage ne s’exécute. Lors de la première utilisation, le provisionnement du bucket peut renvoyerCWSANDBOX_FSS_BUCKET_PROVISIONING. Le client Python effectue automatiquement de nouvelles tentatives en cas d’échecs transitoires des RPC d’instantané, dans la limite d’un budget défini. Si le provisionnement dure plus longtemps que ce budget, réessayez en espaçant progressivement les tentatives, tout en conservant la sandbox source. Lorsque vous relancez la même requête après un échec de transport ambigu, réutilisez un request_id explicite afin que le serveur puisse la dédupliquer. Si un ID d’instantané est disponible après l’expiration du délai, vérifiez cet instantané avant de demander une nouvelle archive. Un instantané passé à l’état FAILED nécessite une nouvelle requête pour capturer à nouveau les données.
Avec le client Python 1.19.6, les échecs transitoires d’instantané peuvent lever SandboxUnavailableError, tandis que les autres échecs d’instantané lèvent SandboxSnapshotError. Pour préserver une compilation, gérez ces deux exceptions et utilisez le champ reason de l’erreur pour déterminer s’il convient de réessayer. En cas d’échec lié au quota ou à la configuration, ne réessayez pas sans en avoir d’abord corrigé la cause.
Le tableau suivant répertorie les causes d’échec courantes et la marche à suivre pour chacune.
Si un exécuteur termine le téléversement de l’archive sans parvenir à enregistrer le résultat, la ligne de l’instantané peut passer à l’état
FAILED alors même qu’un objet existe dans le bucket. Dans ce cas, relancez l’instantané.
En cas d’échec asynchrone, la plateforme émet également un événement sandbox.file_system_snapshot.async_fail, ce qui permet aux systèmes de notification en aval de réagir aux instantanés qui échouent après le retour de l’appel initial.
Limitations
La version 1 de FSS fournit un stockage local temporaire adossé à des instantanés. Il ne s’agit pas d’un système de fichiers partagé, et il ne permet pas de montages actifs accessibles en écriture par plusieurs clients. Pendant leur exécution, les bacs à sable ne peuvent ni lire ni écrire dans les systèmes de fichiers des autres bacs à sable. Ils ne partagent leur état que par la création et la restauration d’instantanés.Exemple avec le SDK
Pour un exemple Python complet et exécutable qui démarre une sandbox, réalise un instantané en cours d’exécution, en crée une branche, capture un instantané à l’arrêt et gère les instantanés, consultezfile_system_snapshots.py dans le dépôt cwsandbox-client. Pour TypeScript, le fichier file-system-snapshots.ts du dépôt cwsandbox-js réalise un instantané en cours d’exécution, le restaure et gère les instantanés.
Ressources associées
- Utilisez votre propre bucket pour les instantanés du système de fichiers : stockez les instantanés dans un bucket dont vous êtes propriétaire.
- Volumes : volumes temporaires et Volumes enregistrés partagés entre plusieurs bacs à sable.
-
Cycle de vie d’une sandbox : fonctionnement de
stop()et des différents états d’une sandbox. - Client Python : installez le SDK et explorez l’API.