> ## 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. # Volumes > Fournissez à une sandbox un espace de stockage temporaire accessible en écriture, ou montez un Volume enregistré partagé par plusieurs bacs à sable. 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](/fr/products/sandboxes/file-system-snapshots) | 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](/fr/products/sandboxes/get-started#forge-api-key), 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`. ```python theme={"system"} 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](/fr/products/sandboxes/file-system-snapshots) 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. ```python theme={"system"} 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. ```python theme={"system"} 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](/fr/products/sandboxes/get-started-cks) 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. ```python theme={"system"} 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`. ```python theme={"system"} 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. ```python theme={"system"} 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](/fr/products/sandboxes/file-system-snapshots) : conserver et restaurer le système de fichiers d’une sandbox. * [Accorder aux bacs à sable l’accès à AI Object Storage](/fr/products/sandboxes/operations/object-storage-access) : lire et écrire dans des buckets depuis une sandbox. * [Configuration du bac à sable](/fr/products/sandboxes/client/guides/sandbox-configuration) : les autres options de création d’une sandbox * [Distributed File Storage](/products/storage/distributed-file-storage/create-volumes) : créer les PersistentVolumeClaims vers lesquelles pointent les Volumes enregistrés.