> ## 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.
# Déployer et gérer un exécuteur
> Déployez un exécuteur sur un cluster CKS, vérifiez son état de santé, mettez à jour sa configuration et supprimez-le.
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](/fr/products/sandboxes/architecture).
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](/fr/products/sandboxes/get-started-cks).
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](https://console.coreweave.com/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](/security/authn-authz/manage-api-access-tokens).
**CLI** : installez la [CoreWeave Intelligent CLI](https://github.com/coreweave/cwic) (`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.
```bash theme={"system"}
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 :
```bash theme={"system"}
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](https://console.coreweave.com/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](/fr/products/sandboxes/profiles/configure).
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 :
```bash theme={"system"}
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 :
```yaml title="runner.yaml" theme={"system"}
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 :
```bash theme={"system"}
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 :
```bash title="Déployer un runner géré" theme={"system"}
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](https://console.coreweave.com/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](https://console.coreweave.com/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](#update-a-runner) ou commencez par le [supprimer](#delete-a-runner). |
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.
```bash theme={"system"}
cwic sandbox runner describe prod-us-east-1
```
Pour obtenir une synthèse rapide sous forme de tableau, utilisez l’alias `get` :
```bash theme={"system"}
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.
```bash title="Fetch a runner" theme={"system"}
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é :
```json theme={"system"}
{
"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
Appliquez un patch d’une ligne depuis stdin :
```bash theme={"system"}
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 :
```yaml title="patch.yaml" theme={"system"}
spec:
release_channel: RELEASE_CHANNEL_RAPID
```
```bash theme={"system"}
cwic sandbox runner edit prod-us-east-1 -f patch.yaml
```
```bash title="Basculer un exécuteur vers le canal RAPID" theme={"system"}
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.
```bash theme={"system"}
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 :
```bash theme={"system"}
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` :
```bash theme={"system"}
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 :
```bash title="Remplacer la politique d’un exécuteur" theme={"system"}
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](/fr/products/sandboxes/profiles/configure).
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](/fr/products/sandboxes/profiles/sunk-integration) pour connaître les annotations disponibles et la configuration requise.
```yaml title="overrides.yaml" theme={"system"}
spec:
overrides:
node_selector:
node-pool: system
tolerations:
- key: dedicated
operator: Equal
value: system
effect: NoSchedule
```
```bash theme={"system"}
cwic sandbox runner edit prod-us-east-1 -f overrides.yaml
```
```bash title="Fixer l'exécuteur sur un Node Pool spécifique" theme={"system"}
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 :
```text title="Example output" theme={"system"}
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.
```bash theme={"system"}
echo 'managed_spec: {allow_privileged_profile_annotations: true}' \
| cwic sandbox runner edit prod-us-east-1 -f -
```
```bash title="Autoriser une posture de profil privilégiée sur un exécuteur" theme={"system"}
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 :
```bash theme={"system"}
cwic sandbox runner upgrade prod-us-east-1
```
```bash title="Appliquer immédiatement une mise à jour disponible" theme={"system"}
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.
```bash theme={"system"}
cwic sandbox runner get
```
Filtrez par zone, cluster ou statut de connexion :
```bash theme={"system"}
cwic sandbox runner get --zone us-east-1
cwic sandbox runner get --connection-status CONNECTED
```
```bash title="Lister les runners gérés" theme={"system"}
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.
```bash theme={"system"}
cwic sandbox runner delete prod-us-east-1
```
La CLI demande une confirmation. Dans un script, passez `--yes` pour ignorer cette confirmation :
```bash theme={"system"}
cwic sandbox runner delete prod-us-east-1 --yes
```
```bash title="Mettre un exécuteur hors service" theme={"system"}
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](/fr/products/sandboxes/operations/node-allocation-budgets) : limitez les demandes de CPU et de mémoire des sandbox par Node Pool ou par groupe de Nœuds.
* [Architecture des bacs à sable](/fr/products/sandboxes/architecture) : 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](/fr/products/sandboxes/profiles/profiles) : comment une sandbox est résolue par rapport à une politique.
* [Configurer une politique de sandbox](/fr/products/sandboxes/profiles/configure) : chaque groupe de contraintes, avec des exemples détaillés.
* [Aperçu de l’API du plan de contrôle](/fr/products/sandboxes/reference/control-plane-api) : 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](/fr/products/sandboxes/reference/profile) : tous les champs que vous pouvez définir dans une politique.