Modèles de sandbox

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

CLI
curl

Créez un modèle à partir d’un fichier :

cwic sandbox template create -f template.json

Affichez le détail des modèles existants et listez-les :

cwic sandbox template describe [TEMPLATE-ID]

cwic sandbox template get

Créer un modèle

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 :

template.json

{
  "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.

Create a sandbox from a template

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.

Override the container per run

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.

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.

template.json

{
  "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.

template.json

{
  "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 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.

template.json

{
  "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.

template.json

{
  "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

CLI
curl

cwic sandbox template edit [TEMPLATE-ID] -f template.json

cwic sandbox template delete [TEMPLATE-ID]

Mettre à jour un modèle

curl -X PATCH https://api.coreweave.com/v1/sandboxTemplates/[TEMPLATE-ID] \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @template.json

Supprimer un modèle

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 : des politiques d’exécuteur complètes à associer à ces modèles.
Configurer une politique de sandbox : les groupes de contraintes au regard desquels la spécification d’un modèle est validée.
Aperçu des politiques : comment les modèles et les politiques se partagent le rôle autrefois assuré par les profils.
Utiliser votre propre capacité de calcul : la configuration de l’exécuteur et votre première sandbox.

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

Créer un modèle

Démarrer un sandbox à partir d’un modèle

Exemples de modèles

Service web avec un point de terminaison HTTPS public

Espace de travail restauré à partir d’un instantané

Trafic sortant sélectif

CKS uniquement : pièces jointes de pod

Gérer les modèles

Étapes suivantes

​Créer un modèle

​Démarrer un sandbox à partir d’un modèle

​Exemples de modèles

​Service web avec un point de terminaison HTTPS public

​Espace de travail restauré à partir d’un instantané

​Trafic sortant sélectif

​CKS uniquement : pièces jointes de pod

​Gérer les modèles

​Étapes suivantes

Créer un modèle

Démarrer un sandbox à partir d’un modèle

Exemples de modèles

Service web avec un point de terminaison HTTPS public

Espace de travail restauré à partir d’un instantané

Trafic sortant sélectif

CKS uniquement : pièces jointes de pod

Gérer les modèles

Étapes suivantes