> ## 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.

# Configurer le plan de données direct pour un exécuteur

> Exposez un point de terminaison d’exécuteur pour que les opérations d’exécution, de journalisation et sur les fichiers des sandboxes contournent la passerelle.

Un point de terminaison de plan de données direct permet au client `cwsandbox` d’acheminer les opérations d’exécution, de journalisation et sur les fichiers directement vers l’exécuteur. Ces opérations utilisent le protocole mTLS (mutual Transport Layer Security) au lieu de transiter par la passerelle CoreWeave Sandboxes. Les appels de cycle de vie et de gestion, eux, continuent de passer par la passerelle.

Cette page s’adresse aux administrateurs qui exploitent un exécuteur géré sur un cluster CoreWeave Kubernetes Service (CKS). Elle aborde les sujets suivants :

* La manière dont le chemin direct atteint l’exécuteur.
* Le choix et la configuration d’un mode d’exposition.
* L’acheminement du point de terminaison via votre propre contrôleur d’ingress.
* La vérification que le point de terminaison est prêt.

## Chemin de connexion directe vers l’exécuteur

Chaque exécuteur géré peut exposer un point de terminaison de plan de données stable, placé en amont de toutes ses répliques. La plateforme résout l'adresse de ce point de terminaison à partir de la configuration `dataPlane` de l’exécuteur et délivre à ce dernier un certificat serveur pour cette adresse. La passerelle CoreWeave Sandboxes renvoie l'adresse aux clients, accompagnée d'un certificat client limité à la sandbox.

```mermaid theme={"system"}
sequenceDiagram
    participant Client as cwsandbox client
    participant API as Sandbox API
    participant EP as Runner endpoint<br/>(your cluster)
    participant Pod as Sandbox pod

    Client->>API: Request a client certificate for a sandbox
    API-->>Client: Certificate + endpoint address
    Client->>EP: mTLS connection (exec, logs, files)
    EP->>Pod: Apply
    Pod-->>EP: Result
    EP-->>Client: Result
```

Les propriétés suivantes de ce chemin déterminent les choix de configuration présentés sur cette page :

* **La session TLS se termine au niveau de l’exécuteur** : l’exécuteur authentifie chaque connexion au moyen d’un certificat client. Les intermédiaires doivent transmettre le flux TCP (Transmission Control Protocol) sans le modifier. C’est notamment le cas des équilibreurs de charge, des contrôleurs d’ingress et des réseaux privés virtuels (VPN). Un proxy qui termine la session TLS puis la chiffre à nouveau, ou qui remplace l’identité du client par un en-tête, rompt le chemin direct.
* **Le certificat serveur est émis pour l’adresse annoncée** : la plateforme dérive les noms alternatifs du sujet (SAN) du certificat à partir de l’adresse que vous configurez. Les clients vérifient l’exécuteur par rapport à ce nom ; l’adresse doit donc être stable et se résoudre vers le point de terminaison.
* **Le Service du plan de données expose un seul port** : chaque mode d’exposition activé crée un Service uniquement pour l’écouteur du plan de données, sur le port TCP `9443`. Un ingress personnalisé peut publier un autre port, par exemple `443`, et le rediriger vers ce Service. Le Service du plan de données n’expose pas les ports d’état de santé, de métriques ou de contrôle.

Les clients qui utilisent la politique de transport `AUTO` par défaut peuvent se replier sur la passerelle si la configuration de la connexion directe n’est pas disponible. En revanche, une erreur `PERMISSION_DENIED` ou `UNAUTHENTICATED` lors de l’émission des identifiants d’authentification entraîne toujours un échec. Si un certificat direct ne dispose pas de l’autorisation requise pour une opération, `AUTO` peut passer par la passerelle. Le repli ne garantit pas qu’une opération déjà envoyée à l’exécuteur puisse être relancée sans risque.

## Prérequis

Avant de configurer le plan de données direct, assurez-vous de remplir les conditions suivantes :

* Déployez un exécuteur géré et vérifiez que `installStatus` a la valeur `RUNNER_INSTALL_STATUS_READY`. Dans les exemples, remplacez `RUNNER_ID` par l’identifiant de votre exécuteur. Pour savoir comment le déployer, consultez [Déployer et gérer un exécuteur](https://docs.coreweave.com/fr/products/sandboxes/operations/managed-runners.md).
* Authentifiez-vous auprès de la CoreWeave Intelligent CLI ou exportez un jeton d’accès à l’API CoreWeave pour `curl`, comme indiqué dans la section [Avant de commencer](https://docs.coreweave.com/fr/products/sandboxes/operations/managed-runners.md#before-you-begin) de la page consacrée à l’exécuteur. Les exemples de cette page utilisent la même variable `$TOKEN`.
* Utilisez un jeton disposant de l’autorisation `sandbox_admin` pour consulter ou mettre à jour l’exécuteur.
* Disposez d’un accès `kubectl` au cluster CKS qui héberge l’exécuteur. Les ressources de l’exécuteur se trouvent dans le namespace `cw-sandbox-system`. Pour les exemples d’exposition personnalisée, installez également Helm et assurez-vous de disposer des autorisations nécessaires pour gérer les ressources de portée cluster, telles que les CustomResourceDefinitions (CRD) et `GatewayClass`.

## Choisir un mode d’exposition

Le champ `spec.data_plane` sélectionne un seul et unique mode d’exposition. Si vous ne définissez pas ce champ, l’exécuteur hérite de la valeur par défaut de la plateforme pour son canal de publication. Définissez explicitement `disabled` pour ne pas hériter d’une valeur par défaut activée.

Dans les adresses suivantes, remplacez `SERVICE_NAME` par le nom du Service de l’exécuteur et `HOSTNAME` par le nom d’hôte configuré.

| Mode | Ce que la plateforme crée dans votre cluster | Adresse annoncée | Cas d’utilisation |
| - | - | - | - |
| `disabled` | Rien | Aucune. Les clients doivent passer par la passerelle pour les nouvelles opérations sur les données. | Le cluster ne peut pas accepter de connexions entrantes, ou vous souhaitez une posture déterministe reposant uniquement sur la passerelle. |
| `cluster_ip` | Un Service `ClusterIP` | `https://SERVICE_NAME.cw-sandbox-system.svc:9443` | Les clients peuvent acheminer le trafic vers les Services du cluster et résoudre le nom DNS du Service du cluster. |
| `load_balancer` | Un Service `LoadBalancer` | `https://HOSTNAME:9443` | Vous souhaitez une adresse publique ou privée dédiée pour le point de terminaison, sans autre ingress sur le chemin. |
| `custom` | Un Service `ClusterIP` | L’`advertised_uri` que vous fournissez | Vous acheminez le trafic via votre propre contrôleur d’ingress, un VPN, un maillage de services ou un réseau superposé. |

La plateforme nomme le Service d’après son identifiant interne pour l’exécuteur. Récupérez donc le nom dans le cluster plutôt que de le déduire. Le Service porte l’étiquette `sandbox.coreweave.com/component=data-plane` :

```bash theme={"system"}
kubectl get svc -n cw-sandbox-system -l sandbox.coreweave.com/component=data-plane
```

Les contraintes suivantes s’appliquent aux modifications :

* Une fois qu’une valeur non vide est définie pour `load_balancer.load_balancer_class`, vous ne pouvez plus la modifier ni l’effacer directement, y compris en passant à un autre mode d’exposition activé. Définissez d’abord `disabled`, attendez que le Service soit supprimé, puis appliquez la nouvelle configuration.
* Un changement de mode d’exposition peut modifier l’adresse annoncée et interrompre les opérations directes actives. Vérifiez à nouveau la connectivité après le changement.

## Exposer le point de terminaison avec un Service LoadBalancer

Le mode `load_balancer` crée un Service `LoadBalancer` qui transfère le port TCP `9443` vers l’exécuteur sans terminaison TLS. Définissez l’accessibilité souhaitée avec `scope` et configurez la sélection d’adresse du fournisseur via `annotations` ou `load_balancer_class`. Indiquez les plages réseau des clients en notation CIDR (classless inter-domain routing) via `source_ranges`. Le fournisseur doit prendre en charge et appliquer ces plages sources.

`hostname` est requis. La plateforme l’inclut dans le certificat du serveur, annonce `https://HOSTNAME:9443` aux clients et définit l’annotation `external-dns.alpha.kubernetes.io/hostname` sur le Service pour les clusters qui exécutent ExternalDNS. Sur CKS, publiez plutôt le nom via l’External Hostname Controller. Ajoutez l’annotation `service.beta.kubernetes.io/external-hostname` et définissez `hostname` sur le nom entièrement qualifié alloué par CKS. La valeur d’annotation courte `runner-a` donne `runner-a.ORG_ID-CLUSTER_NAME.coreweave.app`. Suivez uniquement les instructions d’allocation DNS de [Create a public DNS name](https://docs.coreweave.com/products/networking/ingress-service/create-public-dns-name.md). L’exécuteur fournit son propre certificat TLS ; ne configurez donc pas de terminaison TLS au niveau de l’ingress pour ce point de terminaison.

Pour obtenir une adresse publique sur CKS, ajoutez également `service.beta.kubernetes.io/coreweave-load-balancer-type: public`. Avec la configuration d’adresse CKS par défaut, une adresse privée est attribuée si cette annotation est omise. Pour plus de détails sur la sélection d’adresse, voir [Expose a Service](https://docs.coreweave.com/products/networking/ingress-service/expose-service-dns.md). Une portée `PRIVATE` nécessite soit un `load_balancer_class`, soit une annotation de fournisseur, car la plateforme ne peut pas déduire la manière dont votre fournisseur sélectionne une adresse privée.

Remplacez `ORG_ID` et `CLUSTER_NAME` par l’identifiant de votre organisation et le nom du cluster, puis remplacez `CLIENT_CIDR` dans `source_ranges` par le CIDR d’un réseau depuis lequel vos clients se connectent.

> [tab] CLI
>
> ```yaml title="data-plane.yaml" theme={"system"}
> spec:
>   data_plane:
>     load_balancer:
>       scope: RUNNER_DATA_PLANE_SERVICE_SCOPE_PUBLIC
>       hostname: runner-a.ORG_ID-CLUSTER_NAME.coreweave.app
>       external_traffic_policy: RUNNER_DATA_PLANE_EXTERNAL_TRAFFIC_POLICY_CLUSTER
>       source_ranges:
>         - CLIENT_CIDR
>       annotations:
>         service.beta.kubernetes.io/coreweave-load-balancer-type: public
>         service.beta.kubernetes.io/external-hostname: runner-a
> ```
>
> ```bash theme={"system"}
> cwic sandbox runner edit RUNNER_ID -f data-plane.yaml
> ```

> [tab] curl
>
> ```bash title="Exposer le point de terminaison de l’exécuteur via un LoadBalancer public" theme={"system"}
> curl --fail-with-body -X PATCH \
>   'https://api.coreweave.com/v1/sandbox/managedRunners/RUNNER_ID?updateMask=spec.dataPlane' \
>   -H "Authorization: Bearer $TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "spec": {
>       "dataPlane": {
>         "loadBalancer": {
>           "scope": "RUNNER_DATA_PLANE_SERVICE_SCOPE_PUBLIC",
>           "hostname": "runner-a.ORG_ID-CLUSTER_NAME.coreweave.app",
>           "externalTrafficPolicy": "RUNNER_DATA_PLANE_EXTERNAL_TRAFFIC_POLICY_CLUSTER",
>           "sourceRanges": [
>             "CLIENT_CIDR"
>           ],
>           "annotations": {
>             "service.beta.kubernetes.io/coreweave-load-balancer-type": "public",
>             "service.beta.kubernetes.io/external-hostname": "runner-a"
>           }
>         }
>       }
>     }
>   }'
> ```

Après la mise à jour, l’exécuteur est redéployé avec la nouvelle configuration et le Service apparaît dans le namespace `cw-sandbox-system`. Vérifiez l’adresse et le DNS du Service, puis testez la connexion depuis un client. Une mise à jour de configuration réussie ne garantit pas l’accessibilité réseau.

## Acheminer le point de terminaison via votre propre contrôleur d’ingress

Si votre cluster assure déjà la terminaison du trafic entrant au niveau d’un contrôleur d’ingress, utilisez le mode `custom` pour un point de terminaison situé derrière la même adresse. La plateforme crée un Service `ClusterIP` sur le port `9443`, et vous indiquez dans `advertised_uri` l’adresse que les clients doivent contacter.

Les exigences sont les mêmes que pour tout chemin placé devant l’exécuteur :

* Utilisez le **TLS passthrough** pour la route, avec une correspondance sur l’indication du nom de serveur TLS (SNI) de la connexion. N’effectuez pas la terminaison TLS au niveau du contrôleur d’ingress.
* Définissez `advertised_uri` sur une origine `https://` absolue, sans chemin, requête ni identifiants d’authentification, par exemple `https://runner-a.ORG_ID-CLUSTER_NAME.coreweave.app:443`. L’hôte doit être résolu vers le contrôleur d’ingress, et le port doit correspondre à celui sur lequel le contrôleur écoute.
* Installez des CRD Gateway API compatibles avec votre contrôleur. Le chart Traefik de CoreWeave et l’exemple Envoy Gateway `v1.9.1` prennent tous deux en charge `TLSRoute` en version `v1`. Ne remplacez pas un ensemble de CRD appartenant à un autre composant sans vous coordonner au préalable avec son propriétaire.

Les deux exemples utilisent un nom d’hôte sous le domaine `.coreweave.app` de votre cluster. Traefik s’appuie sur l’enregistrement générique (wildcard) du cluster, tandis que l’exemple Envoy crée un enregistrement spécifique via l’annotation `external-hostname`. Remplacez `ORG_ID` et `CLUSTER_NAME` par vos valeurs.

### Préparer le contrôleur d’ingress

Choisissez le contrôleur que vous utilisez. Les deux configurations exposent un écouteur TLS passthrough pour le nom d’hôte de l’exécuteur sur un Service `LoadBalancer` public doté d’un nom DNS `.coreweave.app`.

> [tab] Traefik (graphique CoreWeave)
>
> Le chart CoreWeave [Traefik](https://docs.coreweave.com/products/cks/clusters/coreweave-charts/traefik.md) peut servir des routes Gateway API sur les mêmes Pods et le même Service `LoadBalancer` que ses routes Ingress. Le Service du chart porte déjà les annotations `service.beta.kubernetes.io/coreweave-load-balancer-type: public` et `service.beta.kubernetes.io/external-hostname: '*'`. Grâce au caractère générique, les noms d’hôte sous `*.ORG_ID-CLUSTER_NAME.coreweave.app` se résolvent en Traefik, sauf si un enregistrement DNS spécifique est prioritaire. Avant d’utiliser le nom d’hôte de l’exécuteur, vérifiez qu’il se résout en l’adresse de Traefik. Si un enregistrement existant pointe ailleurs, choisissez un nom d’hôte inutilisé ou mettez à jour cet enregistrement. Consultez [Gateway API](https://docs.coreweave.com/products/cks/clusters/coreweave-charts/traefik.md#gateway-api) pour connaître les prérequis du chart et les recommandations relatives à la propriété des CRD.
>
> 1. Suivez [Install the Gateway API CRDs](https://docs.coreweave.com/products/cks/clusters/coreweave-charts/traefik.md#install-the-gateway-api-crds) pour installer le bundle du canal standard pris en charge par le chart. Si un bundle compatible est déjà installé, réutilisez-le.
>
> 2. Activez le fournisseur Gateway API et ajoutez un listener TLS passthrough sur le point d’entrée `websecure`. Le `port` du listener correspond au port de conteneur de Traefik (`8443`), et non au port publié par le `LoadBalancer` (`443`) :
>
>    ```yaml title="traefik-values.yaml" theme={"system"}
>    traefik:
>      providers:
>        kubernetesGateway:
>          enabled: true
>      gateway:
>        enabled: true
>        listeners:
>          web:
>            port: 8000
>            protocol: HTTP
>          sandbox-data-plane:
>            port: 8443
>            protocol: TLS
>            hostname: "runner-a.ORG_ID-CLUSTER_NAME.coreweave.app"
>            mode: Passthrough
>            namespacePolicy:
>              from: All
>    ```
>
>    ```bash theme={"system"}
>    helm repo add coreweave https://charts.core-services.ingress.coreweave.com
>    helm upgrade --install traefik coreweave/traefik \
>      --namespace traefik --create-namespace \
>      -f traefik-values.yaml
>    ```
>
>    Si Traefik est déjà installé à partir de ce chart, fusionnez ces valeurs dans votre fichier de valeurs existant, puis mettez à niveau la release.
>
> La Gateway ainsi créée s’appelle `traefik-gateway` et se trouve dans le namespace `traefik`. Utilisez ces valeurs pour `GATEWAY_NAME` et `GATEWAY_NAMESPACE` dans la route ci-dessous.

> [tab] Envoy Gateway
>
> [Envoy Gateway](https://gateway.envoyproxy.io/) prend en charge nativement la Gateway API. Le chart Helm `v1.9.1` utilisé ici inclut des CRD de la Gateway API qui servent `TLSRoute` en version `v1`. Par défaut, Envoy Gateway crée un Service `LoadBalancer` pour chaque `Gateway`. Les annotations CoreWeave rendent l’adresse publique et allouent un nom DNS. Ajoutez-les à une ressource `EnvoyProxy` référencée par la `Gateway`.
>
> 1. Installez Envoy Gateway :
>
>    ```bash theme={"system"}
>    helm upgrade --install eg oci://docker.io/envoyproxy/gateway-helm --version v1.9.1 \
>      --namespace envoy-gateway-system --create-namespace
>    ```
>
>    Si un autre composant gère les CRD de la Gateway API, vérifiez que son bundle est compatible avec Envoy Gateway `v1.9.1` et qu’il sert la version de route utilisée ici. Installez séparément les CRD d’Envoy Gateway avant d’ajouter `--set crds.enabled=false`, car cette option ignore les deux ensembles de CRD. Suivez la [procédure d’installation du chart avec des CRD existants](https://github.com/envoyproxy/gateway/tree/v1.9.1/charts/gateway-helm#skip-install-crds).
>
> 2. Créez une `GatewayClass`, un `EnvoyProxy` portant les annotations de Service CoreWeave, ainsi qu’une `Gateway` dotée d’un listener TLS passthrough sur le port `443`. La valeur courte `runner-a` de `external-hostname` alloue `runner-a.ORG_ID-CLUSTER_NAME.coreweave.app`, qui doit correspondre au nom d’hôte du listener :
>
>    ```yaml title="envoy-gateway.yaml" theme={"system"}
>    apiVersion: gateway.networking.k8s.io/v1
>    kind: GatewayClass
>    metadata:
>      name: envoy
>    spec:
>      controllerName: gateway.envoyproxy.io/gatewayclass-controller
>    ---
>    apiVersion: gateway.envoyproxy.io/v1alpha1
>    kind: EnvoyProxy
>    metadata:
>      name: sandbox-data-plane
>      namespace: envoy-gateway-system
>    spec:
>      provider:
>        type: Kubernetes
>        kubernetes:
>          envoyService:
>            annotations:
>              service.beta.kubernetes.io/coreweave-load-balancer-type: public
>              service.beta.kubernetes.io/external-hostname: runner-a
>    ---
>    apiVersion: gateway.networking.k8s.io/v1
>    kind: Gateway
>    metadata:
>      name: sandbox-data-plane
>      namespace: envoy-gateway-system
>    spec:
>      gatewayClassName: envoy
>      infrastructure:
>        parametersRef:
>          group: gateway.envoyproxy.io
>          kind: EnvoyProxy
>          name: sandbox-data-plane
>      listeners:
>        - name: sandbox-data-plane
>          protocol: TLS
>          port: 443
>          hostname: "runner-a.ORG_ID-CLUSTER_NAME.coreweave.app"
>          tls:
>            mode: Passthrough
>          allowedRoutes:
>            namespaces:
>              from: All
>    ```
>
>    ```bash theme={"system"}
>    kubectl apply -f envoy-gateway.yaml
>    ```
>
> La Gateway s’appelle `sandbox-data-plane` et se trouve dans le namespace `envoy-gateway-system`. Utilisez ces valeurs pour `GATEWAY_NAME` et `GATEWAY_NAMESPACE` dans la route suivante.

### Pointer l’exécuteur vers l’adresse de l’ingress

La valeur `custom.advertised_uri` correspond à l’adresse que contactent les clients : elle doit donc indiquer le nom d’hôte et le port de l’ingress, et non le Service `ClusterIP`.

1. Définissez `custom.advertised_uri` sur l’adresse servie par votre contrôleur d’ingress. Cette configuration crée également le Service du plan de données que cible la route à l’étape suivante.

   > [tab] CLI
   >
   > ```yaml title="data-plane.yaml" theme={"system"}
   > spec:
   >   data_plane:
   >     custom:
   >       advertised_uri: https://runner-a.ORG_ID-CLUSTER_NAME.coreweave.app:443
   > ```
   >
   > ```bash theme={"system"}
   > cwic sandbox runner edit RUNNER_ID -f data-plane.yaml
   > ```

   > [tab] curl
   >
   > ```bash title="Annoncer le point de terminaison de l’exécuteur via votre contrôleur d’ingress" theme={"system"}
   > curl --fail-with-body -X PATCH \
   >   'https://api.coreweave.com/v1/sandbox/managedRunners/RUNNER_ID?updateMask=spec.dataPlane' \
   >   -H "Authorization: Bearer $TOKEN" \
   >   -H "Content-Type: application/json" \
   >   -d '{
   >     "spec": {
   >       "dataPlane": {
   >         "custom": {
   >           "advertisedUri": "https://runner-a.ORG_ID-CLUSTER_NAME.coreweave.app:443"
   >         }
   >       }
   >     }
   >   }'
   > ```

2. Attendez la fin du déploiement progressif de l’exécuteur.

3. Relevez le nom du Service qu’il a créé :

   ```bash theme={"system"}
   kubectl get svc -n cw-sandbox-system -l sandbox.coreweave.com/component=data-plane
   ```

### Lier la route au Service de l’exécuteur

Créez une `TLSRoute` dans le namespace de l’exécuteur afin de lier l’écouteur en mode passthrough au Service du plan de données.

1. Remplacez `GATEWAY_NAME` et `GATEWAY_NAMESPACE` par les valeurs du contrôleur que vous avez préparé, et `SERVICE_NAME` par le nom du Service obtenu à l’étape précédente :

   ```yaml title="runner-tlsroute.yaml" theme={"system"}
   apiVersion: gateway.networking.k8s.io/v1
   kind: TLSRoute
   metadata:
     name: runner-data-plane
     namespace: cw-sandbox-system
   spec:
     parentRefs:
       - name: GATEWAY_NAME
         namespace: GATEWAY_NAMESPACE
         sectionName: sandbox-data-plane
     hostnames:
       - "runner-a.ORG_ID-CLUSTER_NAME.coreweave.app"
     rules:
       - backendRefs:
           - name: SERVICE_NAME
             port: 9443
   ```

   ```bash theme={"system"}
   kubectl apply -f runner-tlsroute.yaml
   kubectl get tlsroute -n cw-sandbox-system runner-data-plane -o yaml
   ```

2. Vérifiez la présence de `Accepted: True` et de `ResolvedRefs: True` dans `status.parents[].conditions`.

3. [Effectuez une vérification depuis un client](#verify-from-a-client) du réseau qui utilise le point de terminaison.

## Vérifier le statut du point de terminaison

Inspectez l’exécuteur après chaque modification de configuration.

1. Vérifiez `installStatus` et `connectionStatus`, et assurez-vous que `activeRevision` a atteint `targetRevision`.

   > [tab] CLI
   >
   > ```bash theme={"system"}
   > cwic sandbox runner describe RUNNER_ID
   > ```

   > [tab] curl
   >
   > ```bash title="Récupérer la configuration et le statut de l’exécuteur" theme={"system"}
   > curl -H "Authorization: Bearer $TOKEN" \
   >   https://api.coreweave.com/v1/sandbox/managedRunners/RUNNER_ID
   > ```

2. Vérifiez le Service du plan de données :

   ```bash theme={"system"}
   kubectl get svc -n cw-sandbox-system -l sandbox.coreweave.com/component=data-plane
   ```

   Pour `load_balancer`, assurez-vous que le Service dispose d’une adresse et que le nom d’hôte configuré se résout bien en cette adresse. Pour `custom`, vérifiez l’adresse du contrôleur d’ingress ainsi que les conditions de la `TLSRoute`.

Ces vérifications ne garantissent pas que le client peut établir une connexion mTLS. Effectuez ensuite la vérification côté client.

## Vérifier depuis un client

Le client Python a besoin de sa propre variable d’environnement de jeton, même si vous avez utilisé `cwic auth login` pour les commandes de gestion. Dans la commande suivante, remplacez `API_ACCESS_TOKEN` par le secret de votre jeton d’accès à l’API CoreWeave.

1. Installez le client dans un environnement virtuel Python actif, comme décrit dans [Préparer votre environnement Python](https://docs.coreweave.com/fr/products/sandboxes/client.md#prepare-your-python-environment) :

   ```bash theme={"system"}
   uv pip install 'cwsandbox>=1.14.2'
   export CWSANDBOX_API_KEY="API_ACCESS_TOKEN"
   ```

2. Exécutez une opération sur l’exécuteur CKS configuré, en définissant la politique de transport du client sur `DIRECT`. Ce mode ne bascule jamais vers la passerelle : un appel réussi prouve donc que le chemin direct fonctionne depuis ce réseau :

   ```python theme={"system"}
   from cwsandbox import AuthStrategy, DataPlaneMode, Sandbox

   with Sandbox.run(
       auth=AuthStrategy.COREWEAVE_API_KEY,
       placement_mode="cks",
       runner_ids=["RUNNER_ID"],
       data_plane_mode=DataPlaneMode.DIRECT,
   ) as sandbox:
       print(sandbox.exec(["echo", "direct"]).result().stdout)
   ```

Si l’appel lève une erreur alors que le même appel avec `DataPlaneMode.GATEWAY` réussit, consultez la section [Dépannage](#troubleshooting). Pour connaître l’ensemble des options du client, consultez [Connexions directes aux sandbox](https://docs.coreweave.com/fr/products/sandboxes/client/guides/direct-connections.md).

## Désactiver le point de terminaison

Définissez `disabled` pour supprimer le Service créé par la plateforme. Les nouvelles opérations en mode `AUTO` peuvent passer par la passerelle lorsque la configuration directe n’est pas disponible. Les opérations forcées sur `DIRECT` échouent si elles ne parviennent pas à établir une connexion directe. Les opérations directes en cours risquent d’être interrompues.

> [tab] CLI
>
> ```bash theme={"system"}
> echo 'spec: {data_plane: {disabled: {}}}' \
>   | cwic sandbox runner edit RUNNER_ID -f -
> ```

> [tab] curl
>
> ```bash title="Désactiver le plan de données direct" theme={"system"}
> curl --fail-with-body -X PATCH \
>   'https://api.coreweave.com/v1/sandbox/managedRunners/RUNNER_ID?updateMask=spec.dataPlane' \
>   -H "Authorization: Bearer $TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "spec": {
>       "dataPlane": {
>         "disabled": {}
>       }
>     }
>   }'
> ```

## Dépannage

| Symptôme | Cause probable | Solution |
| - | - | - |
| Mise à jour rejetée avec l’erreur `load_balancer.hostname must be a stable DNS name` | `hostname` est vide ou n’est pas un nom DNS valide. | Fournissez le nom entièrement qualifié vers lequel se résout le point de terminaison. |
| Mise à jour rejetée avec l’erreur `private scope requires a load_balancer_class or provider annotation` | Portée `PRIVATE` sans aucun moyen de sélectionner une adresse privée. | Ajoutez la classe ou l’annotation du fournisseur. Avec la configuration d’adresse CKS par défaut, omettez `coreweave-load-balancer-type` pour obtenir une adresse privée et transmettez toute autre annotation requise. |
| Mise à jour rejetée avec l’erreur `advertised_uri must be an absolute https origin` | L’identifiant de ressource uniforme (URI) contient un chemin, une requête, des identifiants d’authentification ou un schéma autre que `https`. | Utilisez la forme `https://HOSTNAME:PORT`. |
| Mise à jour rejetée avec l’erreur `load_balancer_class cannot change in place` | Kubernetes ne permet pas de modifier ce champ du Service. | Définissez `disabled`, attendez la suppression du Service du plan de données, puis appliquez la nouvelle configuration. |
| Le point de terminaison est inaccessible en mode `load_balancer` | Le Service n’a pas encore d’adresse, ou le DNS de `hostname` ne se résout pas en celle-ci. | Vérifiez avec `kubectl get svc -n cw-sandbox-system` si un `LoadBalancer` est en attente et contrôlez l’enregistrement DNS. Sur CKS, vérifiez que l’annotation `external-hostname` a bien produit le nom que vous avez configuré. |
| `TLSRoute` signale `ResolvedRefs: False` | La route référence un Service qui n’existe pas encore. | Appliquez d’abord la mise à jour de l’exécuteur, puis copiez le nom du Service dans `backendRefs`. |
| `DIRECT` échoue alors que `GATEWAY` fonctionne | Le réseau client ne peut pas atteindre l’adresse annoncée, ou un intermédiaire effectue la terminaison TLS. | Testez l’accessibilité TCP de l’hôte et du port annoncés depuis le réseau client. En mode `custom`, vérifiez que la route est en mode passthrough et correspond au nom d’hôte SNI. |
| La négociation TLS échoue en raison d’une non-concordance du nom de certificat | Les clients se connectent à un nom que le certificat du serveur ne couvre pas. | Faites correspondre `advertised_uri` ou `hostname` au nom utilisé par les clients, puis attendez que l’exécuteur utilise le nouveau certificat. |

## Voir aussi

Pour savoir où se situent la passerelle et les exécuteurs, consultez [Architecture des bacs à sable](https://docs.coreweave.com/fr/products/sandboxes/architecture.md).
