> ## 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. # API NetworkConfig > Opérations, champs, masques de mise à jour, cycle de vie et erreurs de NetworkConfig pour les politiques réseau dynamiques des sandbox. `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](https://docs.coreweave.com/fr/products/sandboxes/dynamic-network-policies.md). ## 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](https://docs.coreweave.com/fr/products/sandboxes/operations/managed-runners.md). 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](https://docs.coreweave.com/fr/products/sandboxes/dynamic-network-policies.md#supported-changes-and-limits). ## Opérations et authentification Le service est hébergé à l’adresse `https://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. | Appel de procédure distante (RPC) | Annotation HTTP | Résultat | | - | - | - | | `CreateNetworkConfig` | `POST /v1/networkConfigs` | Crée une configuration appartenant à l’appelant et la renvoie. | | `GetNetworkConfig` | `GET /v1/networkConfigs/{networkConfigId}` | Renvoie la configuration souhaitée et son statut. | | `ListNetworkConfigs` | `GET /v1/networkConfigs` | Renvoie `networkConfigs` et un `nextPageToken` facultatif. | | `UpdateNetworkConfig` | `PATCH /v1/networkConfigs/{networkConfigId}` | Applique un masque de mise à jour et renvoie la configuration. | | `DeleteNetworkConfig` | `DELETE /v1/networkConfigs/{networkConfigId}` | Supprime une configuration inutilisée et renvoie une réponse vide. | 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](https://docs.coreweave.com/fr/products/sandboxes/reference/protos.md). `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. | Champ | Signification | | - | - | | `networkConfigId` | ID immuable et unique au sein de l’organisation, conforme à `^[a-z][a-z0-9-]{2,62}$`. Les ID choisis par l’appelant ne doivent pas commencer par le préfixe réservé `nc-`. | | `spec` | `NetworkOptions` souhaitées : `egress`, `ingress`, `denyEgress`, `denyIngress` et `dnsEgress`. | | `etag` | Jeton de concurrence facultatif pour les écritures de l’état souhaité. Envoyez la dernière valeur renvoyée dans la ressource de mise à jour pour rejeter une écriture obsolète. Une mise à jour liée qui réapplique des règles souhaitées inchangées ne vérifie pas le jeton. Si vous l’omettez, la dernière écriture persistée l’emporte. | | `status.sandboxId` | Dernière sandbox liée. Peut brièvement désigner une sandbox à l’état terminal jusqu’à la fin du nettoyage. | | `status.platformManaged` | Indique si la plateforme a créé automatiquement la configuration pour une sandbox. | | `status.createTime`, `status.updateTime` | Horodatages de création et de mise à jour, en sortie uniquement. | 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 : | Chemin Protobuf | Chemin de masque JSON | Effet | | - | - | - | | `spec.egress` | `spec.egress` | Remplace l’intégralité de la liste du trafic sortant, y compris les autorisations de nom d’hôte HTTPS. | | `spec.deny_egress` | `spec.denyEgress` | Modifie l’option de refus du trafic sortant. | | `spec.ingress` | `spec.ingress` | Remplace l’intégralité de la liste des ingress déclarés pour les services `CUSTOM`. | | `spec.deny_ingress` | `spec.denyIngress` | Modifie l’option de refus de l’ingress. | | `spec.dns_egress` | `spec.dnsEgress` | Modifie le mode du port sortant UDP/TCP `53`. | En JSON, encodez `updateMask` sous forme de chaîne séparée par des virgules, par exemple `"spec.egress,spec.denyEgress"`. | Masque | Comportement | | - | - | | Omis | Met à jour les champs modifiables renseignés. Les listes non vides, les options de refus explicitement présentes et un mode DNS autre que `UNSPECIFIED` sont pris en compte dans le masque implicite. Une requête sans champ modifiable renseigné est invalide. | | Explicitement vide | No-op. N’active ni ne rétablit l’application des règles. En Connect JSON, utilisez `"updateMask": ""`. | | Les cinq chemins | `"spec.egress,spec.denyEgress,spec.ingress,spec.denyIngress,spec.dnsEgress"` remplace tous les champs modifiables. Les valeurs omises sont réinitialisées à leurs valeurs par défaut. En protobuf binaire, `"*"` est équivalent. | | Chemins explicites | Remplace uniquement les champs indiqués. Les autres champs conservent leurs valeurs. Les chemins inconnus sont invalides. | 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’état `CREATING` 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 | Motif | Signification et action | | - | - | | `CWSANDBOX_INVALID_REQUEST` | Règles, masque ou combinaison de champs de création non valides, ou règles non prises en charge par l’exécuteur ou sa politique. Un exécuteur qui ne prend pas en charge les mises à jour à chaud renvoie ce motif avec `FAILED_PRECONDITION`. Corrigez la requête ou utilisez un exécuteur sur lequel les mises à jour à chaud sont activées. | | `CWSANDBOX_RESOURCE_EXISTS` | L’ID choisi par l’appelant existe déjà. Choisissez un nouvel ID ou lisez la configuration existante. | | `CWSANDBOX_REQUEST_ID_CONFLICT` | Une requête de création réutilise un `requestId` avec un corps différent. Utilisez un nouveau `requestId` pour la requête modifiée. | | `CWSANDBOX_NETWORK_CONFIG_NOT_FOUND` | La configuration est introuvable ou n’appartient pas à l’organisation de l’appelant. Vérifiez l’ID et l’organisation. | | `CWSANDBOX_NETWORK_CONFIG_IN_USE` | Une autre sandbox dans un état non terminal utilise la configuration, ou une suppression a été tentée pendant son utilisation. Utilisez une configuration distincte ou attendez la fin de l’arrêt. | | `CWSANDBOX_ETAG_MISMATCH` | Le jeton fourni est obsolète (`ABORTED`). Lisez la dernière version de la configuration et réconciliez les modifications avant toute nouvelle tentative. | | `CWSANDBOX_SANDBOX_NOT_READY` | Le délai d’expiration de la requête a été atteint en attendant qu’une sandbox à l’état `CREATING` ou `PREPARING` passe à l’état `RUNNING`. Aucune modification n’a été enregistrée. Vérifiez l’état de la sandbox avant toute nouvelle tentative. | | `CWSANDBOX_SANDBOX_NOT_RUNNING` | La sandbox est en cours d’arrêt ou dans un état terminal et ne peut pas accepter de mise à jour à chaud. Créez une nouvelle sandbox avec les règles requises. | | `CWSANDBOX_RUNNER_UNAVAILABLE` | L’exécuteur de la sandbox est temporairement indisponible ou non connecté. Réessayez en suivant les indications de nouvelle tentative renvoyées. | | `CWSANDBOX_BACKEND_UNAVAILABLE` | Une opération du backend a échoué. L’application des règles a peut-être déjà changé si l’enregistrement du rapport d’état effectif a échoué. Lisez la configuration actuelle, appliquez de nouveau les règles prévues et vérifiez le trafic. | | `CWSANDBOX_COMMAND_TIMEOUT` | Le délai d’expiration a été atteint lors de l’application des règles sur l’exécuteur. Les règles souhaitées sont peut-être déjà enregistrées, et leur application a pu changer partiellement. Lisez la configuration actuelle, appliquez de nouveau les règles prévues et vérifiez le trafic. | | `CWSANDBOX_DNS_EGRESS_UNAVAILABLE` | La dépendance chargée d’appliquer les noms d’hôte HTTPS est indisponible pour une mise à jour élargissant les autorisations. Réessayez en suivant les indications de nouvelle tentative renvoyées. | 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.