> ## 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.
# Modèles de sandbox
> Créez des modèles de sandbox réutilisables, démarrez des Sandbox à partir de ces modèles et joignez des paramètres de pod d’administration sur les clusters CKS.
Un modèle de sandbox est une spécification de sandbox partielle et réutilisable, limitée à l’organisation. Au lieu de répéter la même image de conteneur, les mêmes ressources, les mêmes services et les mêmes règles réseau dans chaque requête de création, vous les enregistrez une fois pour toutes dans un modèle, puis démarrez des Sandbox à partir de celui-ci en ne remplaçant que ce qui change d’un run à l’autre.
Les modèles n’imposent rien. Ils servent de point de départ à une spécification de sandbox, et seule la [politique de l’exécuteur](/fr/products/sandboxes/profiles/configure) applique des règles : un sandbox créé à partir d’un modèle est validé par rapport à la politique exactement comme si vous aviez rédigé vous-même la spécification complète.
Cette page explique comment créer et gérer des modèles et comment démarrer des Sandbox à partir de ceux-ci. Elle fournit également des documents de modèle complets pour des cas d’usage courants. Remplacez `[TEMPLATE-ID]` par l’UUID du modèle, `[SNAPSHOT-ID]` par un ID d’instantané du système de fichiers et `[GITHUB-ORG]` par le nom de votre organisation ou de votre utilisateur GitHub Container Registry.
Créer un modèle
Les modèles sont gérés par les administrateurs de l’organisation. Les opérations d’écriture nécessitent le rôle `sandbox_admin`, mais tout utilisateur de sandbox de l’organisation peut lire les modèles et s’en servir pour démarrer des Sandbox.
Créez un modèle à partir d’un fichier :
```bash theme={"system"}
cwic sandbox template create -f template.json
```
Affichez le détail des modèles existants et listez-les :
```bash theme={"system"}
cwic sandbox template describe [TEMPLATE-ID]
```
```bash theme={"system"}
cwic sandbox template get
```
```bash title="Créer un modèle" theme={"system"}
curl -X POST https://api.coreweave.com/v1/sandboxTemplates \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d @template.json
```
Le corps de requête correspond directement au document du modèle, et non à un objet encapsuleur.
Voici un exemple de modèle minimal d’environnement de développement :
```json title="template.json" theme={"system"}
{
"displayName": "python-dev-box",
"spec": {
"containers": [
{
"name": "main",
"image": "python:3.11",
"resourceRequirements": {
"requests": { "cpu": "1", "memory": "2Gi" },
"limits": { "cpu": "2", "memory": "4Gi" }
}
}
],
"maxLifetimeSeconds": 14400,
"tags": ["dev-box"]
}
}
```
Règles applicables à chaque écriture de modèle :
* **`displayName` est requis** et doit être unique parmi les modèles actifs de l'organisation : de 1 à 128 caractères après suppression des espaces de début et de fin. Privilégiez des noms qui n’ont pas la forme d’un UUID, afin d’éviter tout conflit avec la recherche qui interprète d’abord la valeur comme un ID.
* **`spec` est une spécification de sandbox partielle**, plafonnée à 1 Mio. Elle utilise les mêmes champs qu’une requête de création, et tout son contenu peut être remplacé lors de la création.
* **`spec` ne permet pas encore de sélectionner un type d’instance ni de joindre des réseaux de sandbox.** Tout modèle qui définit `instanceType` ou `networkIds` est rejeté comme non implémenté.
* **Le contenu des modèles est visible par tous les utilisateurs de sandbox de l’organisation.** Un modèle n’est pas un canal de distribution de secrets : les identifiants d’authentification en clair n’y ont pas leur place.
Démarrer un sandbox à partir d’un modèle
Démarrez un sandbox à partir d’un modèle en indiquant son ID. La sélection s’effectue uniquement par UUID ; les noms d’affichage permettent la recherche et l’affichage de la liste, mais pas la création.
```bash title="Create a sandbox from a template" theme={"system"}
curl -X POST https://api.cwsandbox.com/v1/sandboxes:createFromTemplate \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "templateId": "[TEMPLATE-ID]" }'
```
Pour modifier un paramètre au cas par cas pour chaque run, transmettez `overrides` avec la même structure qu’une spécification de sandbox. Tout champ présent dans les remplacements remplace intégralement le champ correspondant, sans fusion :
* Un message que vous définissez remplace l’intégralité du message du modèle. Un message que vous omettez conserve la valeur du modèle.
* Une liste ou une map que vous définissez remplace l’intégralité de la collection du modèle, y compris lorsque vous la définissez comme vide. Pour supprimer une seule entrée, vous devez donc envoyer la collection complète avec le contenu souhaité.
* Remplacer n’importe quel champ du conteneur remplace toute la liste des conteneurs. Il n’est pas possible d’appliquer un patch partiel à un conteneur du modèle : un remplacement qui concerne le conteneur doit donc inclure le conteneur complet, y compris `image`.
```bash title="Override the container per run" theme={"system"}
curl -X POST https://api.cwsandbox.com/v1/sandboxes:createFromTemplate \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"templateId": "[TEMPLATE-ID]",
"overrides": {
"containers": [
{
"name": "main",
"image": "python:3.12",
"command": "sleep",
"args": ["infinity"]
}
]
}
}'
```
La sandbox enregistre la spécification matérialisée lors de sa création, ainsi que l’ID et la révision du modèle source. Modifier ou supprimer le modèle par la suite n’a jamais d’effet sur les Sandbox existantes.
Les clients Python et TypeScript encapsulent ce point de terminaison dans `Sandbox.run_from_template()` et `client.runFromTemplate()`. Pour le flux de travail du SDK, consultez la [documentation du client](/fr/products/sandboxes/client).
Exemples de modèles
Les exemples ci-dessous sont des documents complets à utiliser avec `cwic sandbox template create -f template.json`. Contrairement à une politique, une organisation peut disposer de plusieurs modèles, qui peuvent donc se combiner : créez-en un pour chaque profil de charge de travail récurrent.
Service web avec un point de terminaison HTTPS public
Modèle pour les Sandbox qui exposent un service HTTP sur l’internet public via un point de terminaison HTTPS fourni par la plateforme. L’URL attribuée est renvoyée sur la sandbox après sa création.
```json title="template.json" theme={"system"}
{
"displayName": "public-http-service",
"spec": {
"containers": [
{
"name": "main",
"image": "python:3.11",
"command": "python",
"args": ["-m", "http.server", "8000"]
}
],
"services": [
{
"name": "http",
"port": 8000,
"visibility": "VISIBILITY_PUBLIC",
"endpoint": {
"kind": "ENDPOINT_KIND_HTTPS",
"auth": "ENDPOINT_AUTH_OPEN"
}
}
]
}
}
```
L'exposition publique dépend de la capacité réseau annoncée par l'exécuteur sélectionné : ce modèle ne fonctionne donc que sur les exécuteurs configurés pour des points de terminaison publics.
Espace de travail restauré à partir d’un instantané
Un modèle dont le volume temporaire démarre toujours à partir du même instantané du système de fichiers : un espace de travail de référence dont chaque sandbox crée sa propre copie privée.
```json title="template.json" theme={"system"}
{
"displayName": "golden-workspace",
"spec": {
"containers": [
{
"name": "main",
"image": "python:3.11",
"volumeMounts": [{ "volume": "workspace", "mountPath": "/workspace" }]
}
],
"volumes": [
{
"name": "workspace",
"scratch": {
"size": "10Gi",
"restoreFromSnapshotId": "[SNAPSHOT-ID]"
}
}
]
}
}
```
Consultez [Instantanés du système de fichiers](/fr/products/sandboxes/file-system-snapshots) pour savoir comment créer l’instantané à partir duquel ce modèle effectue la restauration.
Trafic sortant sélectif
Un modèle qui autorise un ensemble fixe de destinations : une plage CIDR sur le port 443, ainsi que les Sandbox au même niveau dans la même organisation. Chaque règle doit s’inscrire dans l’enveloppe `allowedEgress` de la politique de l’exécuteur, faute de quoi la création est rejetée.
```json title="template.json" theme={"system"}
{
"displayName": "curated-egress",
"spec": {
"containers": [{ "name": "main", "image": "python:3.11" }],
"network": {
"egress": [
{ "cidr": { "cidr": "140.82.112.0/20" }, "ports": [{ "port": 443 }] },
{ "tenant": "TENANT_SCOPE_SAME_ORG" }
]
}
}
}
```
Un modèle dont le champ `network.egress` est vide ou omis s’appuie à la place sur la valeur `defaultEgress` de la politique. Définissez la liste de trafic sortant dans le modèle lorsque les destinations de la charge de travail sont connues, et laissez-la vide lorsque la valeur par défaut de la politique offre la posture appropriée.
CKS uniquement : pièces jointes de pod
Sur votre propre cluster CKS, un administrateur peut ajouter un bloc `attachments` à un modèle : il s’agit d’un fragment de spécification de pod Kubernetes appliqué à chaque sandbox créée à partir de ce modèle. C’est ainsi qu’un modèle peut imposer une sélection de nœuds, des tolérances ou un secret de récupération d’image, que la spécification du bac à sable elle-même ne permet pas de définir faute de champs dédiés.
```json title="template.json" theme={"system"}
{
"displayName": "gpu-training",
"spec": {
"containers": [
{
"name": "main",
"image": "ghcr.io/[GITHUB-ORG]/train:latest",
"resourceRequirements": {
"requests": { "cpu": "8", "memory": "32Gi" },
"limits": { "cpu": "8", "memory": "32Gi" }
}
}
]
},
"attachments": {
"spec": {
"nodeSelector": { "workload": "gpu" },
"tolerations": [
{ "key": "nvidia.com/gpu", "operator": "Exists", "effect": "NoSchedule" }
],
"imagePullSecrets": [{ "name": "regcred" }]
},
"metadata": {
"labels": { "team": "ml" }
}
}
}
```
Les pièces jointes modifient le comportement du modèle :
* **Un modèle avec des pièces jointes est réservé à CKS.** Son champ de sortie `requiresCks` vaut true, et toute création à partir de ce modèle avec `mode` défini sur `SANDBOX_MODE_SERVERLESS` échoue avec `FailedPrecondition`. Un mode non défini est traité comme CKS.
* **Les pièces jointes relèvent de l’administrateur.** Seul `sandbox_admin` peut les écrire, les requêtes de création simples ne peuvent pas en fournir, et les remplacements au moment de la création ne peuvent ni les modifier ni les supprimer.
* **Le fragment utilise le format JSON de Kubernetes**, avec des clés en camelCase sous `spec` et `metadata`, contrairement aux champs de spécification du sandbox utilisés dans le reste du modèle. Les clés inconnues sont rejetées.
* **La surface autorisée est volontairement restreinte** : elle se limite aux éléments d’ordonnancement et d’exécution, comme `nodeSelector`, `tolerations`, `imagePullSecrets`, `volumes`, `topologySpreadConstraints`, `hostAliases`, les paramètres DNS et une seule entrée `containers` limitée à `name`, `env`, `envFrom`, `volumeMounts` et `volumeDevices`, ainsi qu’aux libellés et annotations du pod. Les champs sensibles du point de vue de la sécurité sont rejetés, notamment `securityContext`, `runtimeClassName`, `initContainers`, `affinity`, les namespace de l’hôte, les volumes `hostPath` et les comptes de service autres que celui par défaut.
* **Les pièces jointes se superposent au fragment `base` de la politique.** Les champs à valeurs multiples se combinent avec la base de la politique : `imagePullSecrets` et `tolerations` sont dédupliqués, tandis que `topologySpreadConstraints`, `hostAliases` et `readinessGates` sont ajoutés à la suite. Les champs à valeur unique, comme les clés `nodeSelector`, affinent la base. Tout conflit de nom de volume, de variable d’environnement ou de chemin de montage entre les deux couches entraîne le rejet de la création.
Gérer les modèles
```bash theme={"system"}
cwic sandbox template edit [TEMPLATE-ID] -f template.json
```
```bash theme={"system"}
cwic sandbox template delete [TEMPLATE-ID]
```
```bash title="Mettre à jour un modèle" theme={"system"}
curl -X PATCH https://api.coreweave.com/v1/sandboxTemplates/[TEMPLATE-ID] \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d @template.json
```
```bash title="Supprimer un modèle" theme={"system"}
curl -X DELETE https://api.coreweave.com/v1/sandboxTemplates/[TEMPLATE-ID] \
-H "Authorization: Bearer $TOKEN"
```
* **Les lectures acceptent un ID ou un nom d’affichage.** Si le segment de chemin est un UUID valide, la recherche s’effectue par ID ; sinon, il est interprété comme un nom d’affichage parmi les modèles actifs.
* **Chaque mise à jour réussie incrémente la `revision` du modèle.** Chaque sandbox enregistre la révision à partir de laquelle elle a été créée, ce qui vous permet d’identifier les Sandbox antérieures à une modification du modèle.
* **La suppression est réversible.** Les Sandbox existantes ne sont pas affectées, le modèle ne peut plus être sélectionné lors de nouvelles créations, et son nom d’affichage peut être réutilisé pour un nouveau modèle.
Étapes suivantes
* [Exemples de politiques](/fr/products/sandboxes/profiles/profile-examples) : des politiques d’exécuteur complètes à associer à ces modèles.
* [Configurer une politique de sandbox](/fr/products/sandboxes/profiles/configure) : les groupes de contraintes au regard desquels la spécification d’un modèle est validée.
* [Aperçu des politiques](/fr/products/sandboxes/profiles/profiles) : comment les modèles et les politiques se partagent le rôle autrefois assuré par les profils.
* [Utiliser votre propre capacité de calcul](/fr/products/sandboxes/get-started-cks) : la configuration de l’exécuteur et votre première sandbox.