Volumes

Un volume est un espace de stockage qu’une sandbox monte à l’emplacement de votre choix. Les bacs à sable prennent en charge deux types de volumes. Les volumes temporaires appartiennent à une seule sandbox et disparaissent avec elle. Les Volumes enregistrés sont des volumes que votre organisation enregistre une seule fois et que n’importe quel nombre de bacs à sable peut ensuite monter. Cette page s’adresse aux développeurs dont la sandbox doit écrire plus de données que n’en peut contenir le système de fichiers de son conteneur, ou qui souhaitent que plusieurs bacs à sable lisent le même dataset. À l’issue de cette page, vous saurez joindre ces deux types de volumes et gérer le cycle de vie des Volumes enregistrés.

Choisir un type de volume

	Volume temporaire	Volume enregistré
Déclaré par	`ScratchVolumeOptions` à la création de la sandbox	`Volume.create()`, puis `RegisteredVolumeOptions` à la création de la sandbox
Durée de vie	Celle de la sandbox	Indépendante de toute sandbox
Partagé entre bacs à sable	Non	Oui
Stockage sous-jacent	Disque local ou mémoire	Une PersistentVolumeClaim (PVC) existante dans votre cluster
Survit à la suppression de la sandbox	Uniquement via un instantané du système de fichiers	Oui

Utilisez un volume temporaire comme espace de travail au sein d’un même run. Utilisez un Volume enregistré pour les données qui doivent survivre à la sandbox ou que plusieurs bacs à sable lisent simultanément, comme un dataset partagé ou les poids du modèle.

Volumes temporaires

Les exemples de volumes temporaires omettent auth et s’authentifient avec un jeton d’accès à l’API CoreWeave fourni par CWSANDBOX_API_KEY. Pour utiliser une clé API Forge, suivez la procédure décrite dans Premiers pas, puis transmettez les AuthHeaders obtenus à Sandbox.run(). Un volume temporaire est créé en même temps que la sandbox et détruit avec elle. Pour en déclarer un, ajoutez ScratchVolumeOptions à la liste volumes.

from cwsandbox import Sandbox, ScratchVolumeOptions

with Sandbox.run(
    container_image="ubuntu:22.04",
    volumes=[ScratchVolumeOptions(name="workspace", mount_path="/workspace", size="10Gi")],
) as sandbox:
    sandbox.exec(["sh", "-c", "echo hello > /workspace/data.txt"]).result()

ScratchVolumeOptions accepte les champs suivants :

Champ	Description
`name`	Nom du volume dans la sandbox. Les points de montage et les instantanés font référence à ce nom. Requis.
`mount_path`	Chemin absolu où monter le volume sur le conteneur principal. Omettez-le pour déclarer le volume sans le monter.
`size`	Taille du volume, par exemple `"10Gi"`. Omettez-la pour utiliser la valeur par défaut de la plateforme.
`medium`	Stockage sous-jacent : `StorageMedium.DISK` (par défaut) ou `StorageMedium.MEMORY`.
`sub_path`	Chemin relatif dans le volume à monter au lieu de sa racine.
`read_only`	Monte le volume en lecture seule. Valeur par défaut : `False`.
`restore_from_snapshot_id`	Restaure un instantané du système de fichiers dans le volume lors de sa création.

Choisir un support de stockage

Avec StorageMedium.DISK, le volume repose sur le disque local. Avec StorageMedium.MEMORY, il repose sur tmpfs, ce qui est plus rapide, mais l’espace utilisé est décompté de la requête de mémoire du conteneur qui monte le volume ainsi que du plafond de mémoire de la politique. Comme un volume en RAM sans limite pourrait épuiser les ressources du nœud, un volume MEMORY doit déclarer une valeur size. Celle-ci peut être exprimée sous forme de quantité absolue ou de pourcentage entier de la requête de mémoire résolue de la sandbox, par exemple "50%". La forme en pourcentage n’est valide que pour MEMORY. Un volume DISK doit utiliser une taille absolue.

from cwsandbox import Sandbox, ScratchVolumeOptions, StorageMedium

with Sandbox.run(
    container_image="ubuntu:22.04",
    volumes=[
        ScratchVolumeOptions(
            name="fast-cache",
            mount_path="/cache",
            size="50%",
            medium=StorageMedium.MEMORY,
        )
    ],
) as sandbox:
    sandbox.exec(["sh", "-c", "df -h /cache"]).result()

Monter un volume temporaire sur plusieurs conteneurs

mount_path est un raccourci qui monte le volume sur le conteneur principal. Dans une sandbox multiconteneur, omettez mount_path et déclarez plutôt les montages sur chaque conteneur, afin que plusieurs conteneurs puissent accéder au même volume.

from cwsandbox import Container, Sandbox, ScratchVolumeOptions, VolumeMount

with Sandbox.run(
    volumes=[ScratchVolumeOptions(name="shared", size="5Gi")],
    containers=[
        Container(
            name="app",
            image="ubuntu:22.04",
            primary=True,
            volume_mounts=[VolumeMount(volume="shared", mount_path="/data")],
        ),
        Container(
            name="sidecar",
            image="ubuntu:22.04",
            volume_mounts=[VolumeMount(volume="shared", mount_path="/data", read_only=True)],
        ),
    ],
) as sandbox:
    sandbox.exec(["sh", "-c", "echo shared > /data/note.txt"]).result()

Volumes enregistrés

Les exemples suivants utilisent une PVC de votre cluster CKS et un jeton d’accès à l’API CoreWeave défini dans CWSANDBOX_API_KEY. Suivez la procédure Utiliser votre propre capacité de calcul avant d’enregistrer ou de monter un Volume adossé à une PVC. Un Volume enregistré pointe vers une PersistentVolumeClaim (PVC) qui existe déjà dans l’un de vos clusters. Une fois le Volume enregistré, les bacs à sable peuvent monter la demande sans disposer d’un accès au cluster lui-même. Le Volume n’est qu’un pointeur de métadonnées : CoreWeave ne copie jamais les données, et la suppression du Volume n’affecte en rien la demande. Chaque rattachement offre une vue en direct de la même demande : toute écriture effectuée depuis un bac à sable est donc visible par tous les autres bacs à sable qui la montent.

Enregistrer un Volume

Volume.create() renvoie immédiatement le Volume à l’état VALIDATING, puis le plan de contrôle vérifie que la demande existe et qu’elle est utilisable. Interrogez son statut avec wait_until_ready() avant de le monter.

from cwsandbox import PvcVolumeSource, Volume

volume = Volume.create(
    "team-data",
    pvc=PvcVolumeSource(
        runner_id="[RUNNER-ID]",
        namespace="[NAMESPACE]",
        claim_name="[PVC-NAME]",
    ),
    description="Shared training data",
).result()

volume.wait_until_ready(timeout=120).result()
print(volume.state, volume.capacity, volume.access_modes)

Vous choisissez vous-même l’ID du volume. Il doit être unique au sein de votre organisation et ne peut plus être modifié après sa création.

La source et l’option read_only sont également immuables après la création. Seul le champ description peut être modifié par la suite.

PvcVolumeSource accepte les champs suivants :

Champ	Description
`runner_id`	L’exécuteur dont le cluster héberge la demande. Ce champ détermine également où sont planifiés les bacs à sable qui montent le Volume. Requis.
`namespace`	namespace Kubernetes de la demande. Requis.
`claim_name`	Nom du PersistentVolumeClaim. Requis.
`sub_path`	Chemin facultatif, à l’intérieur de la demande, à utiliser comme racine du Volume.

Définissez read_only=True dans Volume.create() pour que la lecture seule devienne une propriété du Volume lui-même. Ce paramètre fixe un minimum, et non une valeur par défaut : un montage peut être en lecture seule sur un Volume accessible en écriture, mais aucun montage ne peut écrire sur un Volume en lecture seule.

Monter un Volume enregistré

Montez le Volume à l’aide de son ID avec RegisteredVolumeOptions. Le Volume doit être à l’état READY au démarrage, faute de quoi la sandbox échoue avec l’erreur CWSANDBOX_VOLUME_NOT_READY.

from cwsandbox import RegisteredVolumeOptions, Sandbox

with Sandbox.run(
    container_image="ubuntu:22.04",
    volumes=[
        RegisteredVolumeOptions(
            name="data",
            volume_id="team-data",
            mount_path="/data",
            read_only=True,
        )
    ],
) as sandbox:
    listing = sandbox.exec(["ls", "/data"]).result()
    print(listing.stdout)
    print(sandbox.attached_volume_ids)

RegisteredVolumeOptions exige name, volume_id et un mount_path absolu autre que /. Il accepte également sub_path, qui se combine avec tout sub_path défini lors de l’enregistrement, ainsi que read_only. Une sandbox indique les Volumes qu’elle a montés dans attached_volume_ids.

Localité et placement

La propriété locality d’un Volume indique s’il impose des contraintes de placement :

cluster_local : le Volume réside dans un seul cluster ; les bacs à sable qui le montent sont donc planifiés sur l’exécuteur de ce cluster. Les Volumes adossés à un PVC sont locaux au cluster.
global : le Volume est accessible depuis n’importe quel cluster et n’impose aucune contrainte de placement.

Il est impossible de monter dans une même sandbox deux Volumes locaux appartenant à des clusters différents : le démarrage échoue alors avec l’erreur CWSANDBOX_VOLUME_PLACEMENT_CONFLICT.

Gérer les Volumes enregistrés

Utilisez les opérations suivantes pour lister, inspecter, mettre à jour et annuler l’enregistrement des Volumes de votre organisation.

from cwsandbox import Volume, VolumeState

# Lister les Volumes de l’organisation, avec filtrage facultatif.
volumes = Volume.list(states=[VolumeState.READY]).result()

# Récupérer un Volume.
volume = Volume.get("team-data").result()
print(volume.state, volume.attached_sandbox_count)

# Mettre à jour la description. C’est le seul champ modifiable.
volume.update(description="Shared training data, 2026 refresh").result()

# Revérifier à tout moment la demande (PVC) sous-jacente.
volume.validate().result()

# Annuler l’enregistrement du Volume. Le PVC sous-jacent reste intact.
volume.delete(allow_missing=True).result()

Volume.list() gère automatiquement la pagination et accepte les filtres states et runner_ids. delete() accepte allow_missing=True, de sorte que la suppression d’un Volume déjà supprimé réussit au lieu de lever une exception. La suppression d’un Volume encore monté par des bacs à sable dans un état non terminal échoue avec l’erreur CWSANDBOX_VOLUME_IN_USE, que le client Python lève sous la forme d’une exception VolumeInUseError. Arrêtez d’abord les bacs à sable associés.

États des volumes

Au cours de son cycle de vie, un Volume enregistré passe par les états suivants :

État	Signification
`VALIDATING`	Le Volume a été accepté et le plan de contrôle vérifie la demande sous-jacente.
`READY`	La validation a réussi. Le Volume peut être monté.
`ERROR`	La validation a échoué. Consultez `state_reason` pour en connaître la cause.
`DELETING`	Le Volume est en cours de désenregistrement et ne peut plus être monté.

wait_until_ready() interroge l’état du Volume jusqu’à ce qu’il passe à READY. La méthode lève VolumeError si le Volume passe à ERROR ou DELETING, et VolumeWaitTimeoutError si le délai d’expiration est écoulé avant.

Motifs d’échec

Utilisez ce tableau pour interpréter les motifs d’échec que peuvent renvoyer les opérations sur les sandbox et les Volumes.

Motif	Signification	Action à mener
`CWSANDBOX_VOLUME_NOT_FOUND`	Aucun Volume portant cet ID n’existe dans votre organisation.	Vérifiez l’ID et l’organisation.
`CWSANDBOX_VOLUME_NOT_READY`	Le démarrage d’une sandbox fait référence à un Volume qui n’est pas `READY`.	Interrogez l’état du Volume jusqu’à ce qu’il soit `READY`, puis relancez le démarrage.
`CWSANDBOX_VOLUME_IN_USE`	La suppression a été bloquée, car des bacs à sable y sont encore associés.	Arrêtez les bacs à sable associés, puis supprimez le Volume.
`CWSANDBOX_VOLUME_BACKEND_NOT_FOUND`	La demande sous-jacente est introuvable ou n’est plus lisible.	Vérifiez que la demande existe toujours dans le namespace, puis appelez `validate()`.
`CWSANDBOX_VOLUME_PLACEMENT_CONFLICT`	Les Volumes associés imposent des exécuteurs incompatibles.	Montez des Volumes situés dans le même cluster.
`CWSANDBOX_VOLUME_QUOTA_EXCEEDED`	L’organisation a atteint sa limite de Volumes.	Supprimez les Volumes inutilisés ou demandez une augmentation de quota.

Pour en savoir plus sur les fonctionnalités connexes des sandbox, consultez les ressources suivantes :

Instantanés du système de fichiers : conserver et restaurer le système de fichiers d’une sandbox.
Accorder aux bacs à sable l’accès à AI Object Storage : lire et écrire dans des buckets depuis une sandbox.
Configuration du bac à sable : les autres options de création d’une sandbox
Distributed File Storage : créer les PersistentVolumeClaims vers lesquelles pointent les Volumes enregistrés.

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

Choisir un type de volume

Volumes temporaires

Choisir un support de stockage

Monter un volume temporaire sur plusieurs conteneurs

Volumes enregistrés

Enregistrer un Volume

Monter un Volume enregistré

Localité et placement

Gérer les Volumes enregistrés

États des volumes

Motifs d’échec

​Choisir un type de volume

​Volumes temporaires

​Choisir un support de stockage

​Monter un volume temporaire sur plusieurs conteneurs

​Volumes enregistrés

​Enregistrer un Volume

​Monter un Volume enregistré

​Localité et placement

​Gérer les Volumes enregistrés

​États des volumes

​Motifs d’échec

​Ressources associées

Choisir un type de volume

Volumes temporaires

Choisir un support de stockage

Monter un volume temporaire sur plusieurs conteneurs

Volumes enregistrés

Enregistrer un Volume

Monter un Volume enregistré

Localité et placement

Gérer les Volumes enregistrés

États des volumes

Motifs d’échec

Ressources associées