NetworkConfigService gère les configurations réseau limitées à l’organisation pour CoreWeave Sandboxes. Chaque configuration contient les NetworkOptions souhaitées et peut être liée à une seule sandbox qui n’est pas dans un état terminal. La mise à jour d’une configuration liée applique les règles à cette sandbox sans la redémarrer. Pour un guide pas à pas, voir Modifier l’accès réseau d’une sandbox en cours d’exécution.
Disponibilité et prérequis
NetworkConfigService nécessite que la prise en charge de NetworkConfig soit activée sur l’API qui dessert votre organisation. Si cette prise en charge n’est pas activée, ses appels de procédure distante (RPC) renvoient UNIMPLEMENTED avec le motif CWSANDBOX_NOT_IMPLEMENTED. Les mises à jour à chaud exigent en outre que les mises à jour réseau à chaud soient activées sur l’exécuteur. Pour les sandboxes sans serveur, CoreWeave gère ces paramètres. Pour un exécuteur géré CoreWeave Kubernetes Service (CKS), définissez spec.overrides.env.ENABLE_LIVE_NETWORK_UPDATE sur la chaîne "true". Voir Gérer les exécuteurs. Si les mises à jour à chaud ne sont pas activées sur l’exécuteur, UpdateNetworkConfig renvoie FAILED_PRECONDITION avec le motif CWSANDBOX_INVALID_REQUEST.
Les mises à jour de noms d’hôte HTTPS nécessitent par ailleurs un exécuteur prenant en charge les noms d’hôte HTTPS, ainsi qu’une sandbox créée avec au moins une autorisation httpsHostname. Voir Modifications prises en charge et limites.
Opérations et authentification
Le service est hébergé à l’adressehttps://api.cwsandbox.com. Les requêtes nécessitent un jeton Bearer disposant de l’autorisation sandbox_user et d’un accès à l’organisation de la configuration. Les mises à jour liées exigent en outre un accès à la sandbox.
Pour utiliser JSON via Connect, envoyez une requête
POST à /coreweave.sandbox.v1.NetworkConfigService/[RPC-NAME] avec le message de requête complet, Content-Type: application/json et Connect-Protocol-Version: 1. Remplacez [RPC-NAME] par une méthode du tableau. Les liaisons REST de création et de mise à jour acceptent en revanche la ressource NetworkConfig comme corps de requête. Les options de requête telles que updateMask sont transmises sous forme de paramètres de requête. Pour les clients générés, voir Protobuf.
NetworkConfigService est distinct de NetworkService, qui n’est pas disponible et concerne les réseaux de sandbox partagés.
Champs de la ressource
Les noms de champs du tableau suivant sont au format JSON camelCase. Les champs Protobuf sont au format snake_case.
L’opération de création accepte un
requestId facultatif. L’opération de liste accepte pageSize, pageToken et un filtre booléen platformManaged facultatif. Omettez ce filtre pour inclure les deux types de propriété. L’opération de suppression accepte allowMissing: true pour aboutir même lorsque l’ID n’existe pas.
Champs de sandbox et de modèle
SandboxSpec.networkConfigId est facultatif lors de la création et immuable par la suite. En l’absence d’ID, la plateforme crée une configuration à partir de l’entrée facultative en écriture seule SandboxSpec.network, ou à partir de règles vides qui se résolvent en valeurs par défaut de la politique. Il n’est pas valide d’envoyer les deux champs.
Les réponses des opérations Get et List sur les sandboxes exposent le networkConfigId lié et omettent le network en ligne. Consultez NetworkConfig.spec pour les règles souhaitées, et les champs status.effectiveEgress, status.effectiveIngress et status.effectiveDnsEgress de la sandbox pour le rapport d’état effectif enregistré.
Un modèle de sandbox conserve le spec.network en ligne comme recette réutilisable et ne peut pas stocker spec.networkConfigId. Chaque sandbox créée à partir du modèle reçoit sa propre configuration managée par la plateforme. Une requête de création à partir d’un modèle peut, à la place, fournir overrides.networkConfigId afin de lier une configuration inutilisée créée par l’appelant. Dans ce cas, ne fournissez pas également overrides.network dans la requête.
Masques de mise à jour
Update prend en charge les chemins suivants :
En JSON, encodez
updateMask sous forme de chaîne séparée par des virgules, par exemple "spec.egress,spec.denyEgress".
Le caractère générique
"*" ne fonctionne qu’en protobuf binaire, par exemple avec gRPC ou Connect en encodage protobuf. Dans les requêtes Connect JSON et dans la valeur de requête REST updateMask, il échoue au décodage avec INVALID_ARGUMENT, avant même d’atteindre le handler. Cette erreur de décodage ne comporte pas de raison CWSANDBOX_*.
Un masque omis ne permet pas d’effacer une liste répétée. Pour effacer le trafic sortant, sélectionnez explicitement spec.egress. Si la liste du trafic sortant ou de l’ingress est vide et que l’option de refus correspondante n’est pas définie ou vaut false, la valeur par défaut de la politique s’applique. Pour refuser le trafic, effacez plutôt la liste et définissez l’option de refus dans la même mise à jour. Une option de refus à true combinée à une liste non vide dans le même sens est invalide.
Pour modifier l’accès DNS, incluez spec.dnsEgress dans le masque et définissez dnsEgress sur DNS_EGRESS_MODE_ALLOW ou DNS_EGRESS_MODE_DENY. Une sandbox ne peut pas demander ALLOW lorsque la politique de l’exécuteur exige DENY. Si vous sélectionnez spec.dnsEgress avec DNS_EGRESS_MODE_UNSPECIFIED, ou si vous sélectionnez ce chemin sans fournir de valeur, la valeur par défaut de la politique de l’exécuteur est rétablie. Il en va de même lorsque vous sélectionnez les cinq chemins pour un remplacement complet. Si la politique ne précise rien, ALLOW s’applique par défaut. Si spec.dnsEgress ne figure pas dans le masque, le mode enregistré est conservé.
Le mode DNS contrôle le trafic vers le port de destination UDP/TCP 53, et non l’autorisation des noms de requête ni le DNS via d’autres transports autorisés. Les autorisations de nom d’hôte HTTPS utilisent egress[].httpsHostname et constituent une autorisation distincte sur le port TCP 443. Le trafic requis par la plateforme sur d’autres ports peut rester autorisé même avec denyEgress.
Comportement d’application et cycle de vie
La création ou la mise à jour d’une configuration non liée valide la syntaxe et enregistre les règles souhaitées. La validation par rapport à la politique de l’exécuteur a lieu lorsqu’une sandbox se lie à la configuration, puis de nouveau lors des mises à jour à chaud. Les mises à jour à chaud s’appuient sur la politique de l’exécuteur actuellement en cache dans la passerelle, qui peut brièvement être en retard sur l’écriture d’une politique. Les règles qui sortent du cadre de la politique sont rejetées, et non restreintes silencieusement. Une mise à jour liée attend qu’une sandbox à l’étatCREATING ou PREPARING atteigne l’état RUNNING, dans le délai imparti à la requête. Si ce délai expire avant, la requête échoue avec CWSANDBOX_SANDBOX_NOT_READY et aucune modification n’est enregistrée. Les mises à jour d’une sandbox en cours d’arrêt ou dans un état terminal échouent avec CWSANDBOX_SANDBOX_NOT_RUNNING. Pour une sandbox en cours d’exécution, la mise à jour résout les règles, enregistre l’état souhaité et procède à l’application. Les listes de règles remplacent les autorisations correspondantes au lieu de s’y ajouter. Les services et leur visibilité restent inchangés.
L’enregistrement et l’application sont deux étapes distinctes. Un échec survenant après l’enregistrement peut entraîner un écart entre les règles souhaitées, les autorisations de trafic réelles et le rapport d’état effectif de la sandbox. Après un échec transitoire de l’application, certaines modifications peuvent déjà avoir pris effet et ne sont pas annulées automatiquement.
Une nouvelle tentative avec les mêmes règles souhaitées relance l’application, même lorsque les règles enregistrées correspondent déjà. Après avoir résolu une erreur pouvant faire l’objet d’une nouvelle tentative, lisez la configuration actuelle et réappliquez les règles voulues. Réconciliez toute non-concordance d’etag avant de réessayer. Le jeton protège l’écriture de l’état souhaité, et non une transaction atomique couvrant l’ensemble des systèmes d’application.
Lorsque la spec résultant d’une mise à jour liée correspond déjà à l’état souhaité enregistré, la mise à jour relance l’application sans vérifier l’etag. Ne comptez pas sur le jeton pour rejeter une nouvelle tentative dont la spécification est inchangée. Un masque de mise à jour explicitement vide reste un no-op et ne relance pas l’application.
Un rejet permanent CWSANDBOX_INVALID_REQUEST émis par l’exécuteur survient avant toute modification de l’application. Si la mise à jour a enregistré de nouvelles règles souhaitées, l’API tente de restaurer la configuration souhaitée précédente. Cette restauration n’est pas garantie et n’écrase pas une mise à jour simultanée plus récente. Relisez la configuration après une erreur. Une restauration modifie l’etag.
Les configurations managées par la plateforme sont supprimées après l’arrêt de leur sandbox. Les configurations créées par l’appelant sont conservées et peuvent être liées de nouveau ou supprimées dès qu’aucune sandbox non terminale ne les utilise. Pour cloner des règles, copiez spec dans une nouvelle configuration. Réutiliser un ID revient à réutiliser la même ressource.
Erreurs
L’ajout de la première autorisation de nom d’hôte HTTPS d’une sandbox par une mise à jour, plutôt qu’à sa création, peut renvoyer
CWSANDBOX_INVALID_REQUEST. Certaines sandboxes plus anciennes rejettent également les modifications de noms d’hôte, y compris les suppressions. Dans ces cas, créez une nouvelle sandbox avec les autorisations de noms d’hôte requises. L’exécuteur doit prendre en charge les autorisations de noms d’hôte HTTPS pour pouvoir les appliquer.