Aperçu de l’API

Le plan de contrôle expose une API REST qui permet de gérer les exécuteurs ainsi que la politique associée à chacun d’eux. Cette page décrit les comportements transversaux (authentification, gestion des versions, format des erreurs et pagination) qui s’appliquent à tous les points de terminaison. Pour connaître le schéma de chaque champ d’une politique, consultez la Référence des politiques. Pour des guides pas à pas orientés tâches qui utilisent ces points de terminaison, consultez Configurer une politique de sandbox et Déployer et gérer un exécuteur.

URL de base et gestion des versions

https://api.coreweave.com/v1/sandbox

Il s’agit de l’URL de base du plan de contrôle. Elle héberge les points de terminaison des exécuteurs documentés sur cette page : déployer des exécuteurs, définir la politique associée à chacun d’eux et consulter leur état. Elle est distincte du plan de données des sandbox, que le client Python cwsandbox utilise pour démarrer des bacs à sable et diffuser en continu les commandes et la sortie (Sandbox.run(), sb.exec(), opérations sur les fichiers). Les opérations du plan de contrôle créent et configurent l’infrastructure qui produit les bacs à sable. Les opérations du plan de données interagissent avec les bacs à sable en cours d’exécution. L’API est versionnée v1. Les modifications additives et rétrocompatibles sont publiées dans v1. Les changements non rétrocompatibles sont publiés sous un nouveau préfixe de version, et CoreWeave les annonce avant leur publication. Une version antérieure de l’API, v1beta2, reste disponible : c’est là que se trouvent les modèles de profil et les liaisons de profil. Ceux-ci sont remplacés par la politique et ne seront pas ajoutés à v1. Les nouvelles intégrations doivent cibler v1.

Authentification

Toutes les requêtes utilisent une authentification par jeton de type Bearer via TLS. Remplacez [API-ACCESS-TOKEN] par un jeton d’accès à l’API CoreWeave :

Authorization: Bearer [API-ACCESS-TOKEN]

Générez un jeton d’accès API depuis la page Tokens de la Cloud Console. Les jetons héritent des autorisations de l’utilisateur auquel ils appartiennent, et le serveur applique ces autorisations à chaque requête. Deux actions de gestion des identités et des accès (IAM) s’appliquent à CoreWeave Sandboxes. Leurs identifiants sont en minuscules et sensibles à la casse :

sandbox_admin : créer, lire, mettre à jour et supprimer des exécuteurs, et définir la politique qui leur est associée. Tous les points de terminaison des runners gérés l’exigent, y compris en lecture. Inclut sandbox_user. Sur les exécuteurs qui utilisent d’anciens profils v1beta2, cette action autorise également les paramètres de profil privilégiés. Ces paramètres comprennent les conteneurs privilégiés, les namespaces de l’hôte et les montages du système de fichiers de l’hôte. Ils peuvent donner aux bacs à sable un accès aux nœuds comparable à celui d’un administrateur de cluster. Le paramètre allow_privileged de la politique v1 régit les privilèges dans l’invité, à l’intérieur de la frontière d’isolation de la sandbox.
sandbox_user : créer et utiliser des bacs à sable, y compris leurs configurations réseau. Cette action ne donne pas accès à l’administration des runners gérés.

Pour accorder ces actions, attribuez le rôle Sandbox Admin ou Sandbox User sur la page Access Policies de la Cloud Console. Le rôle Sandbox Admin accorde sandbox_admin. Le rôle Sandbox User accorde sandbox_user. Pour la description des rôles, consultez Rôles IAM. Pour comprendre le fonctionnement des Access Policies et suivre la procédure d’attribution étape par étape, consultez Gestion des identités et des accès (IAM) et Gérer les Access Policies. Pour en savoir plus sur les jetons, consultez Gérer les jetons d’accès à l’API. Les requêtes non authentifiées renvoient 401 Unauthenticated avec un corps au format google.rpc.Status. La CoreWeave Intelligent CLI (cwic) encapsule ces points de terminaison REST. Les utilisateurs de la CLI s’authentifient une seule fois avec cwic auth login, puis cwic stocke le jeton dans sa configuration locale. Pour le flux de travail en CLI, consultez Configurer une politique de sandbox.

Type de contenu

Tous les corps de requête et de réponse sont au format JSON :

Content-Type: application/json

L’API fonctionne sur HTTP/2 via connectrpc, mais les clients standard de type curl ou fetch fonctionnent de manière transparente. Aucun client gRPC n’est nécessaire. Pour consulter les définitions Protobuf publiées sur lesquelles reposent ces points de terminaison, ainsi que les SDK générés à partir de celles-ci, voir Protobuf. L’API NetworkConfig est servie sur le plan de données des sandbox à l’adresse https://api.cwsandbox.com et utilise sandbox_user. Utilisez-la pour modifier les règles réseau souhaitées d’une sandbox ; le plan de contrôle sert quant à lui à définir la politique de l’exécuteur qui encadre ces règles.

Familles de ressources

Le plan de contrôle expose les exécuteurs gérés comme ressource d’administration :

Famille	Chemin de base	Opérations
Exécuteurs gérés	`/v1/sandbox/managedRunners`	Créer, Obtenir, Lister, Mettre à jour, Supprimer, `:applyAvailableUpdate`

Une politique n’est pas adressable indépendamment. Comme il s’agit d’un champ de l’exécuteur, vous la lisez en récupérant l’exécuteur et vous l’écrivez au moyen d’une mise à jour de l’exécuteur dont le masque cible policy. Chaque écriture remplace l’intégralité du document. Pour la procédure, consultez Configurer une politique de sandbox. Les modèles de profil restent disponibles sur la surface v1beta2 à l’adresse /v1beta2/sandbox/profile-templates, de même que le champ profile_bindings d’un exécuteur. Ils sont remplacés par les politiques, ne font pas partie du modèle v1 et n’y seront pas ajoutés. Pour le modèle conceptuel et la manière dont la passerelle relaie les requêtes d’exécution, consultez Architecture des bacs à sable. Cette page décrit le contrat des points de terminaison.

Pagination

Les points de terminaison de liste prennent en charge la pagination par curseur :

pageSize : taille de la page. Par défaut 50, maximum 100.
pageToken : curseur renvoyé dans le champ nextPageToken de la page précédente. Une chaîne vide indique qu’il n’y a plus de pages.

Paginate managed runners

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

# Suivre le curseur
curl -H "Authorization: Bearer $TOKEN" \
  'https://api.coreweave.com/v1/sandbox/managedRunners?pageSize=50&pageToken=[NEXT-PAGE-TOKEN]'

La CoreWeave Intelligent CLI pagine automatiquement les résultats des commandes de liste, comme cwic sandbox runner get.

Masques de champs lors des mises à jour

Les mises à jour des runners gérés sur l’API v1 acceptent un update_mask facultatif permettant de sélectionner les champs modifiables à mettre à jour. Si le masque est omis ou vide, l’intégralité de la ressource modifiable est remplacée. Le caractère générique * n’est pris en charge qu’en Protobuf binaire, et non dans le paramètre de requête REST updateMask ni dans les requêtes JSON. Les chemins utilisent la notation pointée et des noms de champs en snake_case (convention standard de google.protobuf.FieldMask). Chemins modifiables les plus courants :

Chemin	S’applique à	Objectif
`display_name`	Runner géré	Modifier le nom d’affichage de l’exécuteur.
`identity.runner_group_id`	Runner géré	Modifier le groupe d’exécuteurs utilisé pour l’affinité d’ordonnancement.
`spec`	Runner géré	Remplacer l’intégralité de la configuration du runner géré.
`spec.release_channel`	Runner géré	Changer de canal de publication (`RELEASE_CHANNEL_STABLE` ou `RELEASE_CHANNEL_RAPID`).
`spec.maintenance_policy`	Runner géré	Ajuster les fenêtres de maintenance des mises à jour automatiques.
`spec.overrides`	Runner géré	Remplacer les paramètres de remplacement du déploiement de l’exécuteur, y compris les tolérances, les sélecteurs de nœuds et l’affinité.
`spec.overrides.affinity`	Runner géré	Remplacer l’affinité du Pod de l’exécuteur tout en conservant les autres remplacements au même niveau.
`spec.enforce_resource_limits`	Runner géré	Exiger que les bacs à sable de l’exécuteur déclarent des limites de CPU et de mémoire.
`policy`	Runner géré	Remplacer l’intégralité du document de politique. Seul chemin de masque pris en charge pour la politique.
`profile_bindings`	Runner géré	Remplacer la liste complète des liaisons de profils. Obsolète, `v1beta2` uniquement ; rejeté par les écritures `v1`.

Sur l’interface REST, fournissez le masque sous la forme d’un unique paramètre de requête updateMask dont les valeurs sont séparées par des virgules, en utilisant la forme JSON (camelCase) de chaque chemin, et envoyez directement la ressource comme corps de requête, sans encapsuleur :

curl -X PATCH "https://api.coreweave.com/v1/sandbox/managedRunners/[RUNNER-ID]?updateMask=spec.releaseChannel,spec.maintenancePolicy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "spec": { "releaseChannel": "RELEASE_CHANNEL_RAPID" } }'

La zone et l’ID de cluster de l’exécuteur sont immuables une fois celui-ci créé.

Affinité de l’exécuteur

La spécification de l’exécuteur géré accepte spec.overrides.affinity, un objet Kubernetes Affinity dont les clés suivent la convention camel case de Kubernetes. Elle prend en charge nodeAffinity, podAffinity et podAntiAffinity. Ce champ s’applique uniquement aux Pods de l’exécuteur. Il ne modifie ni le placement des Pods de sandbox ni l’éligibilité au budget de nœud. La valeur résolue deploymentSpec.affinity est uniquement en sortie. Toute mise à jour de l’affinité remplace l’objet entier. Avec updateMask=spec.overrides.affinity, un "affinity": {} explicite efface toutes les règles, y compris l’affinité héritée. Si vous omettez affinity dans le corps de requête avec le même masque, le remplacement défini par le client est supprimé et les valeurs par défaut de la plateforme sont restaurées. Les sélecteurs de nœuds et les tolérances restent indépendants. Pour des exemples CLI et REST, le comportement d’ordonnancement et la vérification de l’enregistrement de session, voir Configurer l’affinité de l’exécuteur. L’équivalent dans l’ancienne version v1beta2 est managed_spec.overrides.affinity.

Erreurs

Les erreurs renvoient un code de statut HTTP approprié et un corps google.rpc.Status.

{
  "code":    3,
  "message": "runner.identity.zone is required",
  "details": []
}

Le tableau suivant répertorie les mappages courants :

HTTP	`code`	Signification
400	3 (`INVALID_ARGUMENT`)	Champ requis manquant, entrée mal formée, spécification non valide.
401	16 (`UNAUTHENTICATED`)	Jeton API manquant ou non valide.
403	7 (`PERMISSION_DENIED`)	Le jeton ne dispose pas de l’autorisation requise pour effectuer l’action.
404	5 (`NOT_FOUND`)	La ressource n’existe pas.
409	6 (`ALREADY_EXISTS`)	`displayName` ou `runnerId` en double, ou tentative de création d’un second exécuteur sur le même cluster.
503	14 (`UNAVAILABLE`)	Dépendance (par exemple, la validation du cluster) temporairement indisponible. Vous pouvez réessayer sans risque.
500	13 (`INTERNAL`)	Erreur inattendue du serveur. Réessayez avec un backoff exponentiel.

Les messages de validation font partie de la surface stable de l’API. Vous pouvez les afficher tels quels aux utilisateurs finaux.

Idempotence

L’API du plan de contrôle offre les garanties d’idempotence suivantes :

Les points de terminaison Delete* sont idempotents. Un appel DELETE sur une ressource déjà supprimée renvoie 404 sans effet de bord.
Les points de terminaison Create* ne sont pas idempotents. Si vous fournissez deux fois le même runnerId ou le même displayName, l’API renvoie 409 Conflict. Pour effectuer une nouvelle tentative sans risque, vérifiez d’abord avec GET si la ressource existe déjà.
Les points de terminaison Update* peuvent faire l’objet de nouvelles tentatives sans risque si vous utilisez un masque de champs et ne définissez que les champs à modifier.

Signaux de pulsation

Les signaux de pulsation (heartbeats) permettent de vérifier que les exécuteurs sont actifs. Si le plan de contrôle ne reçoit aucun signal de pulsation pendant la fenêtre d’activité, le connectionStatus de l’exécuteur passe à DISCONNECTED. Comptez jusqu’à 30 secondes de décalage entre le moment où l’exécuteur devient injoignable et celui où le plan de contrôle en tient compte. Vous pouvez lire connectionStatus ainsi que le champ associé installStatus dans la réponse d’une requête Get sur un exécuteur.

Voir aussi

Gérer les exécuteurs avec Terraform : configurer, importer et mettre à jour des exécuteurs avec le fournisseur Terraform de CoreWeave.
Architecture des bacs à sable : la taxonomie à quatre ressources et la façon dont la passerelle relaie les requêtes d’exécution.
Aperçu des politiques : comment un sandbox est résolu par rapport à une politique.
Configurer une politique de sandbox : flux de travail avec CoreWeave Intelligent CLI et guide pas à pas, champ par champ, de la spécification du profil.
Déployer et gérer un exécuteur : guide pas à pas du cycle de vie de l’exécuteur avec CoreWeave Intelligent CLI et l’API REST.
Référence des politiques : tous les champs que vous pouvez définir dans un profil.
Protobuf : où trouver le module Protobuf publié, quel hôte expose chaque service et comment installer un SDK généré.

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

URL de base et gestion des versions

Authentification

Type de contenu

Familles de ressources

Masques de champs lors des mises à jour

Affinité de l’exécuteur

Erreurs

Idempotence

Signaux de pulsation

Voir aussi

​URL de base et gestion des versions

​Authentification

​Type de contenu

​Familles de ressources

​Pagination

​Masques de champs lors des mises à jour

​Affinité de l’exécuteur

​Erreurs

​Idempotence

​Signaux de pulsation

​Voir aussi

URL de base et gestion des versions

Authentification

Type de contenu

Familles de ressources

Pagination

Masques de champs lors des mises à jour

Affinité de l’exécuteur

Erreurs

Idempotence

Signaux de pulsation

Voir aussi