Créer une sandbox à partir d’un fichier Compose

POST /v1/sandboxes:createFromFile démarre une sandbox à partir d’un fichier téléversé. Vous envoyez un type de fichier et le contenu binaire du fichier ; la passerelle des sandboxes convertit alors le document en spécification de sandbox et suit le même processus de création que POST /v1/sandboxes. Docker Compose (SANDBOX_FILE_TYPE_COMPOSE) est le seul type de fichier accepté. Chaque service du fichier devient un conteneur au sein d’une même sandbox, et le service que vous désignez devient le conteneur principal de la sandbox. La passerelle ne stocke pas le contenu du fichier. GET /v1/sandboxes/{sandboxId} renvoie la spécification convertie. Cette fonctionnalité n’offre pas une équivalence complète avec Docker Compose. Avant d’importer un projet existant, consultez Prise en charge de Compose.

Avant de commencer

Les exemples suivants utilisent une clé API Forge. Voir Premiers pas. Transmettez la clé dans l’en-tête x-wandb-api-key. Pour créer la sandbox dans une entity Forge autre que votre entity par défaut, transmettez également l’en-tête x-entity-id.

export FORGE_API_KEY="[FORGE-API-KEY]"

Vous pouvez également utiliser un jeton d’accès à l’API CoreWeave avec l’action SANDBOX_USER, y compris pour le placement sur CKS. Suivez les instructions de la section Choisir et obtenir des identifiants d’authentification, puis définissez le jeton :

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

Pour chaque requête de ce guide, remplacez -H "x-wandb-api-key: $FORGE_API_KEY" par -H "Authorization: Bearer $CWSANDBOX_API_KEY" afin d’utiliser ce jeton. L’authentification et le format des erreurs sont les mêmes que pour le reste de l’API. Voir Aperçu de l’API.

Champs de la requête

Champ	Requis	Description
`type`	Oui	Type de document. Utilisez `SANDBOX_FILE_TYPE_COMPOSE`.
`contents`	Oui	Octets du fichier, encodés en base64 dans le JSON. UTF-8, 256 Kio maximum.
`primaryService`	Oui	Service qui devient le service principal de la sandbox. Doit désigner un service défini dans `contents`. Aucune valeur par défaut.
`imageOverrides`	Non	Références d’image par service. Les clés doivent désigner des services définis dans le fichier. Utilisez ce champ pour fournir une image récupérable à un service qui nécessiterait sinon une compilation.
`defaultResources`	Conditionnel	CPU et mémoire copiés sur chaque service qui ne définit pas `deploy.resources`. S’applique par conteneur, et non comme un budget de projet. Toute valeur GPU spécifiée ici est rejetée. Requis lorsque le fichier contient plusieurs services et qu’au moins l’un d’eux ne définit pas `deploy.resources`.

La requête accepte également mode, maxLifetimeSeconds, tags, network, objectStorageAccess, annotations, runnerIds et requestId, avec la même signification que pour POST /v1/sandboxes. networkIds renvoie UNIMPLEMENTED. Pour un placement sur CKS, utilisez un jeton d’accès à l’API CoreWeave et configurez les champs de placement comme décrit dans Placement et débordement des sandboxes. Pour les prérequis liés au stockage d’objets, consultez Accorder aux sandboxes l’accès à AI Object Storage. Cette liste de champs est exhaustive. Les volumes, le type d’instance, la classe de runtime, les identifiants d’authentification pour la récupération d’images et les services publiés ne sont pas disponibles sur ce point de terminaison. Utilisez POST /v1/sandboxes si vous en avez besoin.

Créer la sandbox

Écrivez un fichier Compose :

Write compose.yaml

cat > compose.yaml <<'EOF'
services:
  helper:
    image: docker.io/library/busybox:1.36
    command: ["sleep", "3600"]
    expose: ["8080"]
    healthcheck:
      test: ["CMD", "true"]
      interval: 1s
      timeout: 1s
      retries: 3
  main:
    image: docker.io/library/busybox:1.36
    command: ["sleep", "3600"]
    environment:
      HELPER_HOST: helper
    depends_on:
      helper:
        condition: service_healthy
EOF

Envoyez-le via une requête POST, avec contents encodé en base64 :

Create a sandbox from compose.yaml

jq -n --rawfile yaml compose.yaml '{
  type: "SANDBOX_FILE_TYPE_COMPOSE",
  contents: ($yaml | @base64),
  primaryService: "main",
  defaultResources: { requests: { cpu: "100m", memory: "128Mi" } },
  maxLifetimeSeconds: 3600,
  tags: ["from-file"]
}' | curl -sS -X POST https://api.cwsandbox.com/v1/sandboxes:createFromFile \
  -H "x-wandb-api-key: $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @-

La réponse renvoie une sandbox à l’état STATE_CREATING. Interrogez-la régulièrement à l’aide de son sandboxId jusqu’à ce qu’elle atteigne l’état STATE_RUNNING ou un état terminal :

Poll the sandbox

export SANDBOX_ID="[SANDBOX-ID]"

curl -sS "https://api.cwsandbox.com/v1/sandboxes/$SANDBOX_ID" \
  -H "x-wandb-api-key: $FORGE_API_KEY"

La spécification renvoyée comporte deux conteneurs : main, marqué comme principal, et HELPER_HOST, toujours défini sur helper. Dans le sandbox, helper est résolu en 127.0.0.1. Pour relancer une création sans risque, envoyez requestId. Un même requestId associé aux mêmes entrées déclarées renvoie le sandbox existant. Un même requestId associé à des octets différents, y compris lorsque la modification ne porte que sur des caractères d’espacement, renvoie ALREADY_EXISTS avec le motif CWSANDBOX_REQUEST_ID_CONFLICT.

Prise en charge de Compose

Tous les services partagent un même pod et un même namespace réseau. Les noms de service sont résolus en 127.0.0.1, si bien que des valeurs telles que HELPER_HOST: helper et API_BASE: http://main:8080 fonctionnent sans qu’il soit nécessaire de réécrire le fichier. La sandbox ne dispose ni d’adresses IP par service, ni de réseaux bridge, ni de répliques. Les comportements suivants diffèrent de ceux de Docker Compose :

Le démarrage est séquentiel. Les services non principaux démarrent les uns après les autres, avant le service principal. Dimensionnez maxLifetimeSeconds en conséquence. Si un service ne devient jamais prêt, la sandbox reste dans l’état STATE_CREATING.
RUNNING ne suit que le service principal. Le plantage d’un service auxiliaire après son démarrage ne fait pas échouer la sandbox.
healthcheck devient une sonde de démarrage de type exec uniquement. test doit être une chaîne, CMD, CMD-SHELL ou NONE, et les durées doivent être exprimées en secondes entières. Lorsque la sonde a épuisé ses tentatives, le conteneur est arrêté au lieu d’être marqué comme défaillant.
Les ports restent internes au pod. expose et ports déclarent des ports d’écoute, mais rien n’est publié à l’extérieur.
Les images doivent pouvoir être récupérées. Chaque service doit avoir une clé image: dans le fichier ou une entrée dans imageOverrides. Un service qui requiert encore build: renvoie UNIMPLEMENTED.
command et entrypoint suivent les formes shell et exec de Docker. Omettez-les pour utiliser les valeurs par défaut de l’image. Les valeurs explicites null et [] sont rejetées.
Les GPU sont réservés au service principal, via deploy.resources.reservations.devices avec la capacité gpu et un nombre entier positif.
Les noms doivent être des libellés DNS-1123 (my-app, et non My_App) et ne peuvent pas utiliser les préfixes réservés cw-object-store-agent, cw-object-store-agent-restore ou dns-egress.

Clés non prises en charge

Le document doit être autonome : la passerelle ne lit pas votre disque et ne développe pas les variables de votre environnement. Les clés non reconnues ne sont pas ignorées, mais rejetées avec le chemin du champ en cause.

Rejeté	Notes
Interpolation `$VAR` et `${VAR}`	Écrivez `$$` pour obtenir un `$` littéral.
`include`, `extends`, `env_file`	Uniquement `environment` ou `env` en ligne. Les clés sans valeur et les valeurs `null` sont également rejetées.
`volumes`, `tmpfs`, `configs`, `secrets`, montages de liaison	Les projets qui utilisent des volumes nommés ne peuvent pas être importés.
`restart`, `logging`, `profiles`, `stdin_open`, `tty`, `scale`	Non implémentés sur ce runtime.
`network_mode`, `pid`, `ipc`, `extra_hosts`, réseaux nommés	Un pod, un namespace.
Mappages de ports hôte-conteneur, adresses de liaison, plages de ports, protocoles autres que TCP, ports en double entre services	Un seul port d’écoute TCP par entrée, unique dans toute la sandbox.
`depends_on: service_completed_successfully`, ou tout `depends_on` ciblant le service principal	`service_healthy` et `service_started` sont pris en charge entre services non principaux.
Notations de mémoire Compose (`512m`, `2g`, `512mb`)	Utilisez des quantités Kubernetes telles que `512Mi` ou `1Gi`.
Valeurs `user` nommées (`nobody`)	Utilisez un UID numérique.

La passerelle ignore les clés version, name du projet, labels et les clés d’extension x-*. Ne comptez pas sur la transmission des labels à la sandbox.

Erreurs courantes

Les violations de champ sont renvoyées sous forme de détails BadRequest qui indiquent le chemin et la limite concernés. Elles ne reprennent pas le contenu de votre document.

Situation	Code et motif	Champ
`type` omis	`INVALID_ARGUMENT`, `CWSANDBOX_INVALID_REQUEST`	`type`
Type autre que Compose	`UNIMPLEMENTED`, `CWSANDBOX_NOT_IMPLEMENTED`	`type`
`primaryService` omis ou inconnu	`INVALID_ARGUMENT`, `CWSANDBOX_INVALID_REQUEST`	`primary_service`
Service sans `image:` ni `build:`	`INVALID_ARGUMENT`, `CWSANDBOX_INVALID_REQUEST`	`contents.services.<name>`
Service qui requiert encore `build:`	`UNIMPLEMENTED`, `CWSANDBOX_NOT_IMPLEMENTED`	`contents.services.<name>.build`
Fichier de plus de 256 Kio, ou ne constituant pas un document YAML UTF-8 unique	`INVALID_ARGUMENT`, `CWSANDBOX_INVALID_REQUEST`	`contents`
Clé Compose non prise en charge	`INVALID_ARGUMENT`, `CWSANDBOX_INVALID_REQUEST`	Le chemin de la clé
Même `requestId`, octets différents	`ALREADY_EXISTS`, `CWSANDBOX_REQUEST_ID_CONFLICT`	Aucun

Voir aussi

Premiers pas : créez votre première sandbox à partir d’une spécification.
Aperçu de l’API : authentification, gestion des versions et des erreurs.
Variables d’environnement des sandboxes : ce que la plateforme injecte dans chaque conteneur.

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

Créer une sandbox à partir d’un fichier Compose

Avant de commencer

Champs de la requête

Créer la sandbox

Prise en charge de Compose

Clés non prises en charge

Erreurs courantes

Voir aussi

​Avant de commencer

​Champs de la requête

​Créer la sandbox

​Prise en charge de Compose

​Clés non prises en charge

​Erreurs courantes

​Voir aussi

Avant de commencer

Champs de la requête

Créer la sandbox

Prise en charge de Compose

Clés non prises en charge

Erreurs courantes

Voir aussi