Déployer et gérer un exécuteur

Un exécuteur géré est le composant géré par CoreWeave qui exécute les bacs à sable dans votre cluster CKS. Cette page couvre l’ensemble de son cycle de vie : déployer un exécuteur, vérifier qu’il est en bonne santé, ajuster sa configuration à mesure que vos besoins évoluent, puis le supprimer lorsque vous n’en avez plus l’utilité. Pour savoir quelle place occupe l’exécuteur dans l’architecture des bacs à sable et comment la passerelle lui relaie les requêtes, consultez Architecture des bacs à sable. Pour un guide pas à pas, de l’activation d’un exécuteur au lancement de votre première sandbox, consultez Utiliser votre propre infrastructure de calcul.

Avant de commencer

Les exemples CLI et curl de cette page s’authentifient tous deux à l’aide d’un jeton d’accès à l’API CoreWeave. Générez-en un depuis la page Tokens de la Cloud Console, puis copiez la valeur Token Secret. Pour en savoir plus sur les jetons, consultez Gérer les jetons d’accès à l’API. CLI : installez la CoreWeave Intelligent CLI (cwic), puis exécutez cwic auth login et collez le jeton lorsque vous y êtes invité. Le jeton est enregistré dans votre configuration cwic locale, et les commandes suivantes le lisent automatiquement. Il n’est pas nécessaire de définir une variable d’environnement.

cwic auth login

curl : exportez le jeton dans votre shell pour que les exemples de cette page puissent l’utiliser. Remplacez [API-ACCESS-TOKEN] par votre jeton d’accès à l’API CoreWeave :

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

Commandes des exécuteurs

Le groupe cwic sandbox runner permet de gérer les exécuteurs. Le tableau suivant indique, pour chaque tâche du cycle de vie, la commande correspondante. Les sections suivantes présentent ces commandes en contexte.

Objectif	Commande
Déployer un exécuteur (assistant)	`cwic sandbox runner create [RUNNER-ID]`
Déployer un exécuteur à partir d’un fichier	`cwic sandbox runner create [RUNNER-ID] -f runner.yaml`
Lister les exécuteurs	`cwic sandbox runner get` (alias `ls`)
Inspecter un exécuteur	`cwic sandbox runner get [RUNNER-ID]`
Vue détaillée	`cwic sandbox runner describe [RUNNER-ID]`
Modifier un exécuteur	`cwic sandbox runner edit [RUNNER-ID]`
Appliquer une mise à jour disponible	`cwic sandbox runner upgrade [RUNNER-ID]`
Supprimer un exécuteur	`cwic sandbox runner delete [RUNNER-ID]`
Lire la politique de l’exécuteur	`cwic sandbox runner policy get [RUNNER-ID]`
Modifier la politique de l’exécuteur	`cwic sandbox runner policy edit [RUNNER-ID]`

Toutes les entrées acceptent le format YAML ou JSON.

Déployer un exécuteur

Au sein de votre organisation, chaque cluster CKS héberge au plus un exécuteur géré. Pour en déployer un, fournissez les éléments suivants :

Identifiant de l’exécuteur : un identifiant lisible attribué par le client, unique au sein de votre organisation.
Zone : la zone géographique à laquelle appartient le cluster.
Identifiant du cluster (ou nom du cluster) : le cluster CKS sur lequel l’exécuteur s’exécute. Vous trouverez ces deux informations sur la page Clusters de la Cloud Console.
Politique : les règles que l’exécuteur applique aux bacs à sable de son cluster. Une politique est requise pour exécuter des bacs à sable. Si vous l’omettez, CoreWeave en fournit une par défaut lorsque l’exécuteur se connecte. La politique peut définir une durée de vie par défaut des bacs à sable ; la plateforme impose une limite maximale de 30 jours. Voir Configurer une politique de sandbox.

CLI
curl

L’assistant vous demande de manière interactive le cluster, le canal de publication et les fenêtres de maintenance, puis ouvre votre éditeur avec une spécification préremplie avant de la soumettre :

cwic sandbox runner create prod-us-east-1

Le mode fichier accepte le YAML ou le JSON : c’est donc la méthode à privilégier pour des configurations reproductibles, et elle convient particulièrement aux agents comme Claude Code ou Codex qui génèrent des spécifications d’exécuteur à votre place. La CLI peut également lire depuis stdin avec -f -. Remplacez [CLUSTER-NAME] par le nom du cluster CKS sur lequel déployer l’exécuteur :

runner.yaml

identity:
  zone: us-east-1
  cluster_name: [CLUSTER-NAME]
spec:
  release_channel: RELEASE_CHANNEL_STABLE
  maintenance_policy:
    windows:
      - cron: "0 9 * * SAT"
        duration_seconds: 14400
policy:
  display_name: default
  constraints:
    resources:
      default_cpu: "1"
      default_memory: "2Gi"
      max_cpu: "4"
      max_memory: "8Gi"
      require_limits: true
    lifecycle:
      default_lifetime_seconds: 3600

Soumettez la spécification :

cwic sandbox runner create prod-us-east-1 -f runner.yaml

Remplacez [CLUSTER-ID] par l’identifiant du cluster CKS sur lequel déployer l’exécuteur :

Déployer un runner géré

curl -X POST https://api.coreweave.com/v1/sandbox/managedRunners \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Production runner (US East)",
    "identity": {
      "runnerId": "prod-us-east-1",
      "zone": "us-east-1",
      "clusterId": "[CLUSTER-ID]"
    },
    "spec": {
      "releaseChannel": "RELEASE_CHANNEL_STABLE",
      "maintenancePolicy": {
        "windows": [
          { "cron": "0 9 * * SAT", "durationSeconds": 14400 }
        ]
      }
    },
    "policy": {
      "displayName": "default",
      "constraints": {
        "resources": {
          "defaultCpu": "1",
          "defaultMemory": "2Gi",
          "maxCpu": "4",
          "maxMemory": "8Gi",
          "requireLimits": true
        },
        "lifecycle": { "defaultLifetimeSeconds": 3600 }
      }
    }
  }'

Tenez compte des points suivants :

maintenance_policy.windows est facultatif. S’il est défini, les mises à jour automatiques ne s’appliquent que pendant les fenêtres cron spécifiées.
runner_group_id est facultatif. Utilisez-le pour définir une affinité d’ordonnancement lorsque vous disposez de plusieurs exécuteurs dans la même zone.

Erreurs de validation courantes

Erreur	Correction
`runner.identity.zone is required`	Indiquez une zone. Pour trouver les zones dans lesquelles vous disposez d’un cluster CKS (et donc d’un quota pour un exécuteur), consultez la page Clusters de la Cloud console ou exécutez `cwic cluster get`.
`runner.identity.cluster_id or cluster_name is required`	Indiquez l’un ou l’autre. Vous trouverez ces deux valeurs sur la page Clusters de la Cloud console ou en exécutant `cwic cluster get`.
`policy exceeds 256 KiB limit`	Réduisez la taille du document de politique. Le document encodé est plafonné à 256 Kio.
`a managed runner already exists for this cluster`	Un cluster ne peut héberger qu’un seul exécuteur géré. Mettez à jour l’exécuteur existant ou commencez par le supprimer.

Vérifier le statut de l’exécuteur

Après la création, vérifiez le statut de l’exécuteur pour confirmer qu’il a bien été déployé ou, le cas échéant, pour diagnostiquer les problèmes.

CLI
curl

cwic sandbox runner describe prod-us-east-1

Pour obtenir une synthèse rapide sous forme de tableau, utilisez l’alias get :

cwic sandbox runner get prod-us-east-1

Ces deux commandes acceptent l’identifiant de l’exécuteur que vous avez indiqué lors de la création (prod-us-east-1) ou l’UUID attribué par le serveur.

Fetch a runner

curl -H "Authorization: Bearer $TOKEN" \
  https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1

Vous pouvez transmettre l’identifiant de l’exécuteur que vous avez indiqué lors de la création ou l’UUID attribué par le serveur.

La réponse contient deux champs de statut à surveiller :

installStatus : progression du déploiement de l’exécuteur dans votre cluster (PENDING, PROVISIONING, READY ou FAILED).
connectionStatus : état de la connectivité en temps réel (CONNECTED ou DISCONNECTED). Cette valeur est mise à jour par le signal de pulsation (heartbeat) de l’exécuteur. Prévoyez un délai pouvant atteindre 30 secondes.

Lorsque installStatus == FAILED, la réponse inclut un objet installError structuré :

{
  "installError": {
    "reason": "...",
    "message": "...",
    "remediationHints": ["Add toleration for taint 'workload=gpu:NoSchedule'"],
    "occurredAt": "2026-04-24T12:03:11Z"
  }
}

remediationHints indique les actions à entreprendre. diagnosticDetail contient également des journaux internes qu’il est utile de joindre si vous ouvrez un ticket d’assistance.

Mettre à jour un exécuteur

La commande de modification de l’exécuteur prend en charge un assistant interactif ainsi qu’un patch basé sur un fichier. En interne, les mises à jour s’appuient sur un masque de champs : seuls les champs que vous modifiez sont appliqués. Tout le reste est en lecture seule, notamment installStatus, connectionStatus, les horodatages et la spécification de déploiement résolue. Les chemins suivants sont modifiables :

identity.zone
identity.runner_group_id
spec (objet entier)
spec.release_channel
spec.maintenance_policy
spec.overrides
spec.enforce_resource_limits
policy (document entier)

Dans l’API REST, le corps de la requête PATCH est l’exécuteur géré lui-même, sans encapsuleur de requête, et le masque de champs est transmis dans le paramètre de requête updateMask. En l’absence de masque, ou avec updateMask=*, l’intégralité de la ressource modifiable est remplacée. Deux chemins ne sont acceptés que sur l’ancienne interface v1beta2 et sont rejetés lors des écritures d’exécuteur géré en v1 : profile_bindings (configurez plutôt policy) et spec.allow_privileged_profile_annotations.

Mises à jour courantes d’un exécuteur

Les exemples suivants présentent les modifications les plus fréquemment apportées à un exécuteur : changer de canal de publication, remplacer la politique qui lui est associée, ajuster le placement du pod de l’exécuteur dans votre cluster et autoriser les anciens modèles de profil à comporter une posture privilégiée.

Exemple : changer de canal de publication

CLI
curl

Appliquez un patch d’une ligne depuis stdin :

echo 'spec: {release_channel: RELEASE_CHANNEL_RAPID}' \
  | cwic sandbox runner edit prod-us-east-1 -f -

Vous pouvez aussi écrire le patch dans un fichier, puis le soumettre :

patch.yaml

spec:
  release_channel: RELEASE_CHANNEL_RAPID

cwic sandbox runner edit prod-us-east-1 -f patch.yaml

Basculer un exécuteur vers le canal RAPID

curl -X PATCH "https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1?updateMask=spec.releaseChannel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identity": { "runnerId": "prod-us-east-1" },
    "spec": { "releaseChannel": "RELEASE_CHANNEL_RAPID" }
  }'

Exemple : remplacer la politique

La politique est remplacée en tant que document complet. Lisez la politique actuelle, modifiez ce dont vous avez besoin, puis renvoyez-la. Il n’existe aucun masque au niveau des champs dans policy : un corps partiel efface donc les groupes que vous omettez. Une mise à jour de politique inclut également un etag, le jeton de révision opaque que l’exécuteur renvoie lorsque vous lisez la politique. Envoyez la valeur issue de la lecture sur laquelle repose votre modification, et non une valeur plus récente. Un jeton obsolète provoque un échec avec FAILED_PRECONDITION et ne modifie rien : une modification concurrente est ainsi signalée au lieu d’être écrasée silencieusement.

CLI
curl

cwic sandbox runner get prod-us-east-1 -o json > runner.json
jq '.[0].policy' runner.json > policy.json

Modifiez policy.json, puis soumettez-le en l’associant à l’etag issu de cette même lecture :

cwic sandbox runner policy edit prod-us-east-1 -f policy.json \
  --etag "$(jq -r '.[0].etag' runner.json)"

policy get exporte la politique sans son etag, et policy edit -f sans --etag lit la révision actuelle de l’exécuteur au moment de la soumission : aucune de ces commandes ne vous lie donc à la révision dont provient votre fichier. Lire le jeton séparément, par exemple avec policy describe après l’export, présente la même faille : un jeton plus récent que votre document passe la vérification et écrase la modification effectuée entre-temps. Le modèle de cwic sandbox runner edit évite cette étape supplémentaire : --print-template exporte ensemble les paramètres modifiables, la politique et son etag, et -f utilise la valeur présente dans le fichier.

Lisez l’exécuteur pour capturer à la fois sa politique actuelle et son etag :

curl -H "Authorization: Bearer $TOKEN" \
  https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1 \
  | jq '{policy, etag}' > policy-and-etag.json

Modifiez l’objet policy dans ce fichier, puis renvoyez-le avec l’etag qui l’accompagnait :

Remplacer la politique d’un exécuteur

curl -X PATCH "https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1?updateMask=policy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @policy-and-etag.json

Pour l’ensemble des groupes de contraintes et des exemples détaillés, consultez Configurer une politique de sandbox.

Exemple : fixer le placement sur des nœuds via les remplacements de déploiement

Le champ spec.overrides configure le pod de l’exécuteur lui-même, et non les pods des bacs à sable. Utilisez-le lorsque le pod de l’exécuteur a besoin de tolérances, de sélecteurs de nœuds ou de classes de runtime spécifiques pour être placé sur les bons nœuds. Un cas courant consiste à acheminer le pod de l’exécuteur via le SUNK Pod Scheduler afin qu’il puisse s’exécuter dans votre cluster SUNK aux côtés des tâches Slurm. Définissez le nom de l’ordonnanceur et les annotations SUNK dans les remplacements de l’exécuteur. Consultez Intégration du SUNK Pod Scheduler pour connaître les annotations disponibles et la configuration requise.

CLI
curl

overrides.yaml

spec:
  overrides:
    node_selector:
      node-pool: system
    tolerations:
      - key: dedicated
        operator: Equal
        value: system
        effect: NoSchedule

cwic sandbox runner edit prod-us-east-1 -f overrides.yaml

Fixer l'exécuteur sur un Node Pool spécifique

curl -X PATCH "https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1?updateMask=spec.overrides" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identity": { "runnerId": "prod-us-east-1" },
    "spec": {
      "overrides": {
        "nodeSelector": { "node-pool": "system" },
        "tolerations":  [ { "key": "dedicated", "operator": "Equal", "value": "system", "effect": "NoSchedule" } ]
      }
    }
  }'

Exemple : autoriser une posture de profil privilégiée

allow_privileged_profile_annotations détermine si les modèles de profil hérités liés à un exécuteur peuvent comporter une posture privilégiée. Ce paramètre s’applique aux exécuteurs qui utilisent encore des liaisons de profil plutôt qu’une politique ; la requête est donc envoyée à la surface v1beta2. Sa valeur par défaut est false, et tout modèle comportant une telle posture est rejeté sur un exécuteur où l’option n’est pas définie. Malgré son nom, cette option régit deux types de contenu :

Les annotations de pod privilégiées, c’est-à-dire les préfixes du runtime et de l’ordonnanceur.
Les champs structurés privilégiés de la spécification de pod, tels que serviceAccountName, les namespace de l’hôte, les volumes hostPath, ainsi que les conteneurs privilégiés ou avec élévation de privilèges.

Un modèle rejeté par un exécuteur renvoie permission_denied et indique les champs en cause. Par exemple, un modèle qui définit securityContext.appArmorProfile et securityContext.seccompProfile échoue avec l’erreur suivante :

Example output

Error: updating runner: permission_denied: profile_bindings[7]: template
"[TEMPLATE-ID]" contains privileged pod-spec fields
[securityContext.appArmorProfile securityContext.seccompProfile];
runner does not have allow_privileged_profile_annotations=true

Définissez l’option sur l’exécuteur qui a rejeté le modèle. L’option est limitée à un seul exécuteur : répétez donc cette opération pour chaque exécuteur qui nécessite la posture privilégiée.

CLI
curl

echo 'managed_spec: {allow_privileged_profile_annotations: true}' \
  | cwic sandbox runner edit prod-us-east-1 -f -

Autoriser une posture de profil privilégiée sur un exécuteur

curl -X PATCH https://api.coreweave.com/v1beta2/sandbox/managed-runners/prod-us-east-1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "runner": {
      "id": "prod-us-east-1",
      "managedSpec": { "allowPrivilegedProfileAnnotations": true }
    },
    "updateMask": "managedSpec.allowPrivilegedProfileAnnotations"
  }'

Une fois la mise à jour effectuée, appliquez de nouveau le modèle de profil qui avait été rejeté.

Cette option étend les capacités des bacs à sable de l’exécuteur, notamment l’accès aux ressources de l’hôte. Ne la définissez que sur les exécuteurs qui requièrent la posture privilégiée.

Déclencher à la demande une mise à jour de l’exécuteur

Lorsque updateAvailable vaut true sur l’exécuteur, vous pouvez appliquer la mise à jour immédiatement plutôt que d’attendre la prochaine fenêtre de maintenance :

CLI
curl

cwic sandbox runner upgrade prod-us-east-1

Appliquer immédiatement une mise à jour disponible

curl -X POST https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1:applyAvailableUpdate \
  -H "Authorization: Bearer $TOKEN"

Le plan de contrôle détermine la dernière version disponible sur le canal de publication de l’exécuteur et incrémente target_revision. Le contrôleur exécuté dans le cluster en assure ensuite le déploiement.

Lister les exécuteurs

Pour afficher tous les exécuteurs de votre organisation, ou pour restreindre la vue à une zone, un cluster ou un état de connexion donné, utilisez les commandes de liste suivantes.

CLI
curl

cwic sandbox runner get

Filtrez par zone, cluster ou statut de connexion :

cwic sandbox runner get --zone us-east-1
cwic sandbox runner get --connection-status CONNECTED

Lister les runners gérés

curl -H "Authorization: Bearer $TOKEN" \
  'https://api.coreweave.com/v1/sandbox/managedRunners?pageSize=50&zone=us-east-1'

Paramètres de requête pris en charge : zone, clusterId, connectionStatus, runnerId, managementMode, pageSize (50 par défaut, 100 au maximum) et pageToken. La pagination repose sur des curseurs.

Supprimer un exécuteur

Supprimez un exécuteur lorsque vous n’avez plus besoin de capacité de sandbox sur son cluster, ou avant de redéployer un nouvel exécuteur sur le même cluster.

CLI
curl

cwic sandbox runner delete prod-us-east-1

La CLI demande une confirmation. Dans un script, passez --yes pour ignorer cette confirmation :

cwic sandbox runner delete prod-us-east-1 --yes

Mettre un exécuteur hors service

curl -X DELETE https://api.coreweave.com/v1/sandbox/managedRunners/prod-us-east-1 \
  -H "Authorization: Bearer $TOKEN"

La suppression d’un exécuteur entraîne le démontage de son déploiement dans votre cluster. Tous les bacs à sable en cours d’exécution sur cet exécuteur s’arrêtent. La politique faisant partie de l’exécuteur, elle est supprimée en même temps que lui. Conservez le document de politique dans un système de gestion de versions si vous prévoyez de redéployer le cluster.

La suppression est définitive. Si vous souhaitez simplement suspendre le trafic, déplacez les bacs à sable vers un autre exécuteur avant de supprimer celui-ci.

Voir aussi

Configurer les budgets d’allocation des Nœuds : limitez les demandes de CPU et de mémoire des sandbox par Node Pool ou par groupe de Nœuds.
Architecture des bacs à sable : le modèle de ressources, la distinction entre plan de contrôle et plan de données, et la topologie multicluster.
Aperçu des politiques : comment une sandbox est résolue par rapport à une politique.
Configurer une politique de sandbox : chaque groupe de contraintes, avec des exemples détaillés.
Aperçu de l’API du plan de contrôle : l’authentification, les masques de champs, ainsi que la structure des requêtes et des réponses de chaque point de terminaison.
Référence des politiques : tous les champs que vous pouvez définir dans une politique.

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

Déployer et gérer un exécuteur

Avant de commencer

Commandes des exécuteurs

Déployer un exécuteur

Erreurs de validation courantes

Vérifier le statut de l’exécuteur

Mettre à jour un exécuteur

Mises à jour courantes d’un exécuteur

Exemple : changer de canal de publication

Exemple : remplacer la politique

Exemple : fixer le placement sur des nœuds via les remplacements de déploiement

Exemple : autoriser une posture de profil privilégiée

Déclencher à la demande une mise à jour de l’exécuteur

Lister les exécuteurs

Supprimer un exécuteur

Voir aussi

​Avant de commencer

​Commandes des exécuteurs

​Déployer un exécuteur

​Erreurs de validation courantes

​Vérifier le statut de l’exécuteur

​Mettre à jour un exécuteur

​Mises à jour courantes d’un exécuteur

​Exemple : changer de canal de publication

​Exemple : remplacer la politique

​Exemple : fixer le placement sur des nœuds via les remplacements de déploiement

​Exemple : autoriser une posture de profil privilégiée

​Déclencher à la demande une mise à jour de l’exécuteur

​Lister les exécuteurs

​Supprimer un exécuteur

​Voir aussi

Avant de commencer

Commandes des exécuteurs

Déployer un exécuteur

Erreurs de validation courantes

Vérifier le statut de l’exécuteur

Mettre à jour un exécuteur

Mises à jour courantes d’un exécuteur

Exemple : changer de canal de publication

Exemple : remplacer la politique

Exemple : fixer le placement sur des nœuds via les remplacements de déploiement

Exemple : autoriser une posture de profil privilégiée

Déclencher à la demande une mise à jour de l’exécuteur

Lister les exécuteurs

Supprimer un exécuteur

Voir aussi