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 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 importent AUTH 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 :

export WANDB_API_KEY="[WANDB-API-KEY]"

Python
TypeScript

uv pip install 'cwsandbox[wandb]>=1.14.2'

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.WANDB

sandbox-client.mts

import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/wandb";

export const client = createSandboxClientFromEnv();

Utilisez le jeton de votre organisation CoreWeave. Remplacez [API-ACCESS-TOKEN] par votre jeton :

export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

Python
TypeScript

uv pip install 'cwsandbox>=1.14.2'

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.COREWEAVE_API_KEY

sandbox-client.mts

import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node";

export const client = createSandboxClientFromEnv();

Pour un placement sur CKS, choisissez le jeton CoreWeave, activez un exécuteur et définissez placement_mode="cks" lors de la création de la Sandbox ou dans SandboxDefaults. En TypeScript, choisissez le jeton CoreWeave et définissez un tableau runnerIds non vide pour sélectionner CKS. Créer 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.

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

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
TypeScript

from sandbox_auth import AUTH
from cwsandbox import Sandbox, ScratchVolumeOptions

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

L’exemple TypeScript utilise le client issu de la configuration d’identifiants d’authentification que vous avez choisie.

import { client } from "./sandbox-client.mts";

await client.withSandbox(
  (sandbox) => sandbox.commands.run(["sh", "-c", "echo hello > /workspace/data.txt"], { check: true }),
  {
    containerImage: "ubuntu:22.04",
    volumes: [{ name: "workspace", mountPath: "/workspace", size: "10Gi" }],
  },
);

En TypeScript, les volumes temporaires acceptent name, mountPath, size et restoreFromSnapshotId. Le client TypeScript ne prend en charge ni medium, ni sub_path, ni read_only, ni la configuration directe des montages par conteneur. Pour ces options, utilisez le client Python.

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 sandbox_auth import AUTH
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,
        )
    ],
    resources={"cpu": "1", "memory": "1Gi"},
    auth=AUTH,
) 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 sandbox_auth import AUTH
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")],
            resources={"cpu": "1", "memory": "1Gi"},
        ),
        Container(
            name="sidecar",
            image="ubuntu:22.04",
            volume_mounts=[VolumeMount(volume="shared", mount_path="/data", read_only=True)],
            resources={"cpu": "1", "memory": "1Gi"},
        ),
    ],
    auth=AUTH,
) as sandbox:
    sandbox.exec(["sh", "-c", "echo shared > /data/note.txt"]).result()

Volumes enregistrés

Les Volumes enregistrés adossés à une PVC décrits dans ce guide nécessitent un jeton d’accès à l’API CoreWeave ainsi que l’activation des Volumes enregistrés pour votre organisation. L’onglet clé API Forge de la section Choisir l’authentification s’applique aux volumes temporaires. 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 Sandbox 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 une Sandbox est donc visible par toutes les autres Sandbox qui la montent. Le client TypeScript n’expose pas d’API permettant d’enregistrer ou de gérer des Volumes, ni d’options de montage de Volumes enregistrés pour create() et run(). Utilisez le client Python pour ces opérations. Dans la version 1.0.0 du client TypeScript, runFromTemplate() peut hériter des Volumes enregistrés et de leurs montages définis dans un modèle de Sandbox. Omettez containerImage pour conserver les conteneurs et les montages du modèle. Si vous définissez containerImage, ce paramètre remplace les conteneurs et supprime leurs montages. Si des Volumes enregistrés se retrouvent sans montage, la requête est rejetée.

Enregistrer un Volume

L’enregistrement, la mise à jour ou la suppression d’un Volume nécessite le rôle Sandbox Admin. Le rôle Sandbox User permet de lister, de lire, de valider et de monter des Volumes enregistrés. Le rôle Sandbox Admin inclut les autorisations du rôle Sandbox User. Voir Rôles Sandbox. 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 AuthStrategy, PvcVolumeSource, Volume

volume = Volume.create(
    "team-data",
    auth=AuthStrategy.COREWEAVE_API_KEY,
    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 Sandbox 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 AuthStrategy, RegisteredVolumeOptions, Sandbox

with Sandbox.run(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    placement_mode="cks",
    container_image="ubuntu:22.04",
    volumes=[
        RegisteredVolumeOptions(
            name="data",
            volume_id="team-data",
            mount_path="/data",
            read_only=True,
        )
    ],
    resources={"cpu": "1", "memory": "1Gi"},
) 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 AuthStrategy, Volume, VolumeState

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

# Récupérer un Volume.
volume = Volume.get("team-data", auth=AuthStrategy.COREWEAVE_API_KEY).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 Sandbox 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 Sandbox 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 l’authentification

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 l’authentification

​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 l’authentification

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