Instantanés du système de fichiers

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 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, 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
API HTTP

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.

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
API HTTP

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)

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.

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
API HTTP

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.

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.

API HTTP
API HTTP

Par défaut, snapshot() attend que l’instantané soit READY, puis renvoie son ID.

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é.

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.

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 fileSystemSnapshotId sur 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.

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
API HTTP

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.

# 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 dans le dépôt cwsandbox-client.

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.

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

Instantanés du système de fichiers

Fonctionnement

Démarrer un sandbox avec un montage d’instantané

Système de fichiers temporaire vierge

Restaurer à partir d’un instantané

Prendre un instantané

Instantané à l’arrêt

Instantané en cours d’exécution

Créer une branche à partir d’un instantané

Gérer les instantanés

Statut des instantanés et échecs

Limitations

Exemple avec le SDK

​Fonctionnement

​Démarrer un sandbox avec un montage d’instantané

​Système de fichiers temporaire vierge

​Restaurer à partir d’un instantané

​Prendre un instantané

​Instantané à l’arrêt

​Instantané en cours d’exécution

​Créer une branche à partir d’un instantané

​Gérer les instantanés

​Statut des instantanés et échecs

​Limitations

​Exemple avec le SDK

​Ressources associées

Fonctionnement

Démarrer un sandbox avec un montage d’instantané

Système de fichiers temporaire vierge

Restaurer à partir d’un instantané

Prendre un instantané

Instantané à l’arrêt

Instantané en cours d’exécution

Créer une branche à partir d’un instantané

Gérer les instantanés

Statut des instantanés et échecs

Limitations

Exemple avec le SDK

Ressources associées