> ## Documentation Index > Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt > Use this file to discover all available pages before exploring further. # Instantanés du système de fichiers > Créez un instantané du répertoire de travail d’un sandbox dans le stockage d’objets, puis restaurez-le ou dupliquez-le dans de nouveaux sandboxes. Les exemples qui omettent `auth` utilisent un jeton d’accès à l’API CoreWeave fourni par `CWSANDBOX_API_KEY`. Pour vous authentifier avec une clé API Forge, suivez la page [Premiers pas](/fr/products/sandboxes/get-started#forge-api-key) et transmettez les `AuthHeaders` obtenus à l’opération. Les exemples d’API HTTP utilisent une clé API Forge définie dans `FORGE_API_KEY`. Pour utiliser plutôt un jeton d’accès à l’API CoreWeave, définissez `CWSANDBOX_API_KEY` sur ce jeton et remplacez `-H "x-wandb-api-key: $FORGE_API_KEY"` par `-H "Authorization: Bearer $CWSANDBOX_API_KEY"` dans chaque requête. Utilisez les identifiants d’authentification du compte propriétaire du sandbox et de ses instantanés. Les instantanés du système de fichiers (FSS) permettent à un sandbox d’écrire dans un répertoire de travail local, de capturer ce répertoire dans le stockage d’objets sous forme d’instantané immuable, puis de le restaurer ultérieurement dans de nouveaux sandboxes. Utilisez les FSS pour suspendre et reprendre le système de fichiers d’un sandbox d’un run à l’autre, ou pour dupliquer un instantané dans plusieurs sandboxes qui évoluent ensuite indépendamment les uns des autres.

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 un `EmptyDir` 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 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 bacs à sable. La suppression d’une sandbox ne supprime pas ses instantanés, et la suppression d’un instantané n’a aucune incidence sur les bacs à sable déjà lancés à partir de celui-ci. Par défaut, CoreWeave provisionne et gère le bucket de stockage d’objets qui contient vos instantanés. Pour stocker plutôt vos instantanés dans un bucket que vous possédez et contrôlez, consultez [Utilisez votre propre bucket](/fr/products/sandboxes/file-system-snapshots/bring-your-own-bucket), qui détaille les prérequis relatifs au compte CoreWeave et au bucket.

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 theme={"system"} from cwsandbox import Sandbox, FileSystemSnapshotOptions with Sandbox.run( container_image="ubuntu:22.04", file_system_snapshot=FileSystemSnapshotOptions(mount_path="/work", size="10Gi"), ) as sandbox: sandbox.exec(["sh", "-c", "echo hello > /work/data.txt"]).result() ``` Définissez `fileSystem.mountPath` et `fileSystem.size`. Ne définissez pas `fileSystemSnapshot` pour démarrer avec un système de fichiers vide. ```bash theme={"system"} curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes \ -H "x-wandb-api-key: $FORGE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "containerImage": "ubuntu:22.04", "command": "sleep", "args": ["3600"], "fileSystem": { "mountPath": "/work", "size": "10Gi" } }' ```

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 theme={"system"} from cwsandbox import Sandbox, FileSystemSnapshotOptions with Sandbox.run( container_image="ubuntu:22.04", file_system_snapshot=FileSystemSnapshotOptions( mount_path="/work", file_system_snapshot_id="fss_...", ), ) as sandbox: contents = sandbox.exec(["cat", "/work/data.txt"]).result() print(contents.stdout) ``` ```bash theme={"system"} curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes \ -H "x-wandb-api-key: $FORGE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "containerImage": "ubuntu:22.04", "command": "sleep", "args": ["3600"], "fileSystem": { "mountPath": "/work", "size": "10Gi", "fileSystemSnapshot": { "fileSystemSnapshotId": "fss_..." } } }' ``` Un instantané doit être à l’état `READY` pour pouvoir être restauré. La restauration d’un instantané encore à l’état `CREATING` échoue. Consultez [Statut et échecs des instantanés](#snapshot-status-and-failures).

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 theme={"system"} sandbox.stop(snapshot_on_stop=True).result() print(sandbox.file_system_snapshot_id) ``` `StopSandbox` renvoie un `fileSystemSnapshotId` lorsque la requête d’instantané est acceptée. Si `waitForReady` est défini sur `true`, l’appel attend que l’instantané atteigne l’état `READY` ou `FAILED`, dans la limite de `maxTimeoutSeconds`. Sinon, l’appel peut se terminer alors que l’instantané est encore à l’état `CREATING`. Remplacez `[SANDBOX-ID]` par l’ID de la sandbox à arrêter. ```bash theme={"system"} curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes/[SANDBOX-ID]/stop \ -H "x-wandb-api-key: $FORGE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "sandboxId": "[SANDBOX-ID]", "fileSystemSnapshotOnStop": true, "waitForReady": true, "idempotencyKey": "stop-[SANDBOX-ID]-snapshot-1", "maxTimeoutSeconds": 600 }' ```

Instantané en cours d’exécution

Un instantané en cours d’exécution capture une sandbox active sans l’arrêter. La sandbox continue ensuite de s’exécuter. Par défaut, `snapshot()` attend que l’instantané soit `READY`, puis renvoie son ID. ```python theme={"system"} snapshot_id = sandbox.snapshot().result() print(f"Created snapshot {snapshot_id}") ``` `CreateFileSystemSnapshot` accepte les mêmes paramètres de contrôle `idempotencyKey`, `waitForReady` et `maxTimeoutSeconds` que l’instantané à l’arrêt. Contrairement à `StopSandbox`, `waitForReady` a pour valeur par défaut `true`. Remplacez `[SANDBOX-ID]` par l’ID de la sandbox active dont vous souhaitez créer un instantané. ```bash theme={"system"} curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes/[SANDBOX-ID]/file-system-snapshots \ -H "x-wandb-api-key: $FORGE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "sandboxId": "[SANDBOX-ID]", "waitForReady": true, "maxTimeoutSeconds": 600 }' ``` Lorsque `waitForReady` est défini sur `false`, une réponse réussie signifie simplement que la ligne de l’instantané a été créée et que la commande d’instantané a été envoyée. L’archive peut encore être à l’état `CREATING` et passer ultérieurement à l’état `FAILED`. Interrogez l’état de l’instantané avant de le restaurer.

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. 1. Créez un instantané `READY`, soit avec un instantané à l’arrêt, soit avec un instantané en cours d’exécution. 2. Démarrez la sandbox A en définissant `fileSystemSnapshotId` sur cet instantané. 3. Démarrez la sandbox B avec le même `fileSystemSnapshotId`. 4. 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 theme={"system"} from cwsandbox import Sandbox, FileSystemSnapshotOptions # Restaurer le même instantané dans deux bacs à sable indépendants. with Sandbox.run( file_system_snapshot=FileSystemSnapshotOptions(mount_path="/work", file_system_snapshot_id=snapshot_id), ) as fork_a, Sandbox.run( file_system_snapshot=FileSystemSnapshotOptions(mount_path="/work", file_system_snapshot_id=snapshot_id), ) as fork_b: fork_a.exec(["sh", "-c", "echo a >> /work/data.txt"]).result() fork_b.exec(["sh", "-c", "echo b >> /work/data.txt"]).result() ```

Gérer les instantanés

Listez, récupérez et supprimez les instantanés indépendamment des bacs à sable qui les ont créés. ```python theme={"system"} from cwsandbox import Sandbox # Lister tous les instantanés de votre organisation. snapshots = Sandbox.list_snapshots().result() # Récupérer les détails d’un instantané. snapshot = Sandbox.get_snapshot(snapshot_id).result() print(f"{snapshot.file_system_snapshot_id}: {snapshot.size_bytes} bytes") # Supprimer un instantané. missing_ok rend l’appel idempotent. Sandbox.delete_snapshot(snapshot_id, missing_ok=True).result() ``` Remplacez `[SNAPSHOT-ID]` par l’ID de l’instantané à récupérer ou à supprimer. ```bash theme={"system"} # Lister les instantanés limités à l’organisation. curl https://api.cwsandbox.com/v1beta2/file-system-snapshots \ -H "x-wandb-api-key: $FORGE_API_KEY" # Obtenir un instantané. curl https://api.cwsandbox.com/v1beta2/file-system-snapshots/[SNAPSHOT-ID] \ -H "x-wandb-api-key: $FORGE_API_KEY" # Supprimer un instantané. curl -X DELETE https://api.cwsandbox.com/v1beta2/file-system-snapshots/[SNAPSHOT-ID] \ -H "x-wandb-api-key: $FORGE_API_KEY" ``` `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 un `fileSystemSnapshotId` 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, récupérez l’instantané et consultez deux champs : * `status` : l’état du cycle de vie. Les valeurs finales sont `READY` et `FAILED`. L’API HTTP renvoie la forme entièrement qualifiée, par exemple `FILE_SYSTEM_SNAPSHOT_STATUS_READY`. * `statusReason` : renseigné lorsque `status` vaut `FAILED`, pour indiquer la cause de l’échec. Interrogez `GetFileSystemSnapshot` jusqu’à ce que l’instantané atteigne l’état `READY` 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. Le tableau suivant répertorie les causes d’échec courantes et la marche à suivre pour chacune. | Raison | Signification | Marche à suivre | | - | - | - | | `CWSANDBOX_FSS_BUCKET_PROVISIONING` | Le bucket d’instantanés par défaut est encore en cours de provisionnement. | Réessayez dans quelques instants. Si l’erreur persiste, contactez l’assistance. | | `CWSANDBOX_FSS_AUTH_FAILED` | L’échange d’identifiants d’authentification ou l’autorisation d’accès au bucket a échoué. | Réessayez une fois la politique du bucket ou la politique WIF corrigée. S’il s’agit d’un bucket managé par CoreWeave, contactez l’assistance. | | `CWSANDBOX_FSS_TRANSPORT_FAILED` | L’exécuteur n’a pas pu joindre le stockage d’objets, ou le transfert de l’archive a échoué. | Réessayez. Si le problème se reproduit, contactez l’assistance en indiquant l’ID de l’instantané. | | `CWSANDBOX_FSS_BACKEND_THROTTLED` | Le stockage d’objets a renvoyé une limitation de débit prolongée ou des erreurs backend. | Réessayez plus tard. | | `CWSANDBOX_FSS_CREATE_TIMED_OUT` | L’instantané ne s’est pas terminé dans le délai d’expiration configuré. | Réessayez avec une valeur `maxTimeoutSeconds` plus élevée, ou réduisez le volume de données. | | `CWSANDBOX_FSS_CANCELED` | L’instantané a été annulé, généralement à la suite d’une suppression forcée de la sandbox pendant une opération en cours. | Relancez l’instantané si vous avez toujours besoin des données. | | `CWSANDBOX_FSS_QUOTA_EXCEEDED` | L’organisation a atteint son plafond de nombre d’instantanés ou de stockage. | Supprimez les instantanés inutilisés, ou demandez une augmentation de quota. | | `CWSANDBOX_FSS_NOT_READY` | Une restauration faisait référence à un instantané qui n’est pas `READY`. | Interrogez l’instantané jusqu’à ce qu’il soit `READY`, ou choisissez-en un autre. | | `CWSANDBOX_FSS_NOT_FOUND` | L’instantané n’existe pas dans votre organisation. | Vérifiez l’ID de l’instantané et l’organisation. | | `CWSANDBOX_FSS_SIZE_EXCEEDED` | La taille de système de fichiers demandée dépasse la taille d’espace temporaire prise en charge. | Demandez un système de fichiers plus petit, ou contactez l’assistance au sujet des limites. | 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, le duplique, capture un instantané à l’arrêt et gère les instantanés, consultez [`file_system_snapshots.py`](https://github.com/coreweave/cwsandbox-client/blob/main/examples/file_system_snapshots.py) dans le dépôt `cwsandbox-client`. * [Utilisez votre propre bucket pour les instantanés du système de fichiers](/fr/products/sandboxes/file-system-snapshots/bring-your-own-bucket) : stockez les instantanés dans un bucket dont vous êtes propriétaire. * [Volumes](/fr/products/sandboxes/volumes) : volumes temporaires et Volumes enregistrés partagés entre plusieurs bacs à sable. * [Cycle de vie d’une sandbox](/fr/products/sandboxes/client/guides/sandbox-lifecycle) : fonctionnement de `stop()` et des différents états d’une sandbox. * [Client Python](/fr/products/sandboxes/client) : installez le SDK et explorez l’API.