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

# Architecture des bacs à sable

> Comment les runners, les politiques et la passerelle s’articulent sur un ou plusieurs clusters CKS.

Cette page décrit l’articulation des composants de CoreWeave Sandboxes. Elle s’adresse aux administrateurs qui déploient des runners, rédigent une politique ou planifient un déploiement multi-cluster.

Les bacs à sable CoreWeave reposent sur deux ressources que vous gérez (le **runner géré** et la **sandbox**), sur la **politique** associée à chaque runner et sur un composant d’infrastructure exploité par CoreWeave (la **passerelle**), qui sert d’intermédiaire pour chaque requête de sandbox. Ces composants se répartissent entre deux surfaces de service (un **plan de contrôle** pour la configuration et un **plan de données** pour le trafic) et s’étendent sur autant de clusters CKS que vous choisissez d’en activer.

Pour suivre le guide pas à pas qui permet d’activer un runner et de lancer une sandbox, consultez [Utiliser votre propre capacité de calcul](/fr/products/sandboxes/get-started-cks). Pour savoir comment une sandbox est résolue par rapport à une politique, consultez [Aperçu des politiques](/fr/products/sandboxes/profiles/profiles).

<h2 id="sandbox-resources">
  Ressources de sandbox
</h2>

* **Runner géré** : un composant exploité par CoreWeave qui s’exécute dans l’un de vos clusters CKS. Le runner place, supervise et supprime les bacs à sable de ce cluster. Chaque cluster héberge au plus un runner géré, que CoreWeave maintient à jour sur le canal `RELEASE_CHANNEL_STABLE` ou `RELEASE_CHANNEL_RAPID` de votre choix.
* **Politique** : ce que les bacs à sable d’un cluster peuvent demander, et ce qu’ils obtiennent par défaut. Une politique n’est pas une ressource autonome et ne dispose d’aucun point de terminaison propre : il s’agit d’un champ du runner, si bien que chaque cluster est régi par une seule et unique politique. Pour en rédiger une, consultez [Configurer une politique de sandbox](/fr/products/sandboxes/profiles/configure).
* **Sandbox** : une charge de travail isolée qui s’exécute sur votre cluster. Une sandbox se décrit intégralement elle-même : elle déclare l’image, les ressources de calcul, l’accès réseau et la durée de vie dont elle a besoin. Les bacs à sable sont créés à la demande via le [client Python](/fr/products/sandboxes/client).

La **passerelle** n’est pas une ressource que vous créez ou dont vous êtes propriétaire. Il s’agit d’un service CoreWeave, accessible à l’adresse `api.cwsandbox.com`, qui authentifie chaque appel client, choisit un runner éligible pour héberger la sandbox et relaie le trafic entre le client et le runner propriétaire de chaque sandbox. Une fois la sandbox en cours d’exécution, ses opérations sur les données peuvent également transiter par une connexion mTLS directe qui contourne la passerelle. Voir [Connexions directes aux sandbox](/fr/products/sandboxes/client/guides/direct-connections).

<h3 id="key-constraints">
  Contraintes clés
</h3>

* Un cluster héberge au plus un runner géré, et chaque runner est associé à exactement une politique. Une politique régit donc un cluster. Pour exécuter des bacs à sable selon une posture différente, déployez un runner sur un autre cluster et attribuez-lui sa propre politique.
* Une politique est requise. Une politique vide est valide et déclare une posture entièrement permissive : la posture d’un cluster est ainsi toujours déclarée explicitement, et jamais héritée par accident.
* Une politique peut définir une durée de vie par défaut pour les bacs à sable ; la plateforme applique la durée maximale de 30 jours.
* La modification d’une politique s’applique aux bacs à sable créés après celle-ci. Les bacs à sable en cours d’exécution conservent la politique résolue lors de leur lancement.
* Il n’existe aucune portée par utilisateur ou par équipe au sein d’un cluster. Une politique s’applique à chaque bac à sable placé sur ce cluster, quel que soit son créateur.

<h2 id="resource-relationships">
  Relations entre les ressources
</h2>

L’exécuteur fait le lien entre les deux. Il porte la politique qui régit son cluster et place chaque sandbox sur ce cluster. Une sandbox déclare ses besoins, et la politique détermine si cette requête est autorisée.

```mermaid theme={"system"}
graph LR
    R[Runner géré]
    PL[Politique de l’exécuteur]
    S[Spécification du bac à sable]
    P[Sandbox]

    R -->|porte| PL
    S -->|déclare ses besoins| PL
    PL -->|autorise ou rejette, puis configure| P
    R -->|place| P
```

L’exécuteur fusionne la spécification du bac à sable avec les valeurs par défaut de la politique, la spécification étant prioritaire, puis vérifie que le résultat respecte les contraintes. Toute violation est rejetée au lieu d’être restreinte en silence, et le message d’erreur précise ce qui a été refusé. Voir [Aperçu des politiques](/fr/products/sandboxes/profiles/profiles#how-a-sandbox-resolves-against-a-policy).

<h2 id="multi-cluster-scope">
  Portée multi-cluster
</h2>

Chaque cluster dispose de son propre exécuteur et de sa propre politique. Les utilisateurs n'ont pas besoin de connaître cette topologie : ils demandent au SDK une sandbox avec la configuration requise, et la passerelle achemine la requête vers un cluster dont la politique l'accepte.

```mermaid theme={"system"}
graph TB
    Client[Client / SDK Python]
    GW[Passerelle]

    subgraph C3 [Cluster CKS C]
        direction TB
        R3[Runner géré + politique]
        S3A[sandbox]
        S3B[sandbox]
        R3 --> S3A
        R3 --> S3B
    end
    subgraph C2 [Cluster CKS B]
        direction TB
        R2[Runner géré + politique]
        S2A[sandbox]
        R2 --> S2A
    end
    subgraph C1 [Cluster CKS A]
        direction TB
        R1[Runner géré + politique]
        S1A[sandbox]
        S1B[sandbox]
        R1 --> S1A
        R1 --> S1B
    end

    Client --> GW
    GW <-->|mTLS| R1
    GW <-->|mTLS| R2
    GW <-->|mTLS| R3
```

Pour le placement CKS, la passerelle sélectionne les ressources de calcul parmi les clusters de votre organisation. En l’absence de restriction par identifiant d’exécuteur, elle choisit un cluster qui dispose de capacité disponible et dont la politique de l’exécuteur autorise la requête de sandbox.

Comme la posture est définie au niveau de chaque cluster, une équipe qui a besoin à la fois d’un environnement permissif et d’un environnement restreint utilise deux clusters, et non deux configurations sur un même cluster.

<h2 id="how-sandboxes-launch">
  Lancement des bacs à sable
</h2>

Les ressources transitent par deux surfaces de service. C’est dans le **plan de contrôle**, accessible à l’adresse `api.coreweave.com`, que vous définissez les exécuteurs ainsi que la politique associée à chacun d’eux. C’est dans le **plan de données**, accessible à l’adresse `api.cwsandbox.com`, que les bacs à sable sont lancés et exploités. Cette séparation compte lorsque vous analysez les défaillances et le contrôle d’accès : une panne du plan de contrôle bloque les modifications des exécuteurs et des politiques, sans affecter les bacs à sable déjà en cours d’exécution, tandis qu’une panne du plan de données perturbe le trafic en cours des bacs à sable, sans toucher à la configuration stockée dans le plan de contrôle.

<h3 id="control-plane-one-time-setup">
  Plan de contrôle : configuration initiale
</h3>

Un administrateur utilise la CoreWeave Intelligent CLI ou l’API REST pour déployer un exécuteur sur un cluster CKS et définir la politique qui lui est associée. Le plan de contrôle déploie ensuite l’exécuteur dans le cluster, et l’exécuteur remonte son état via son signal de pulsation (heartbeat).

```mermaid theme={"system"}
sequenceDiagram
    participant Admin as cwic / REST API
    participant CP as Control plane<br/>api.coreweave.com
    participant Runner as Managed runner

    Admin->>CP: Deploy runner on a cluster
    CP-->>Runner: Deploy runner to cluster
    Runner-->>CP: Heartbeat (connected, ready)
    Admin->>CP: Set the runner's policy
    CP-->>Admin: Updated runner
```

Cette étape s’effectue une fois par cluster, puis de nouveau à chaque modification de la politique. Pour les flux de travail correspondants, voir [Configurer une politique de sandbox](/fr/products/sandboxes/profiles/configure) et [Déployer et gérer un runner](/fr/products/sandboxes/operations/managed-runners).

<h3 id="data-plane-sandbox-launch">
  Plan de données : lancement d’une sandbox
</h3>

Lorsqu’un client démarre une sandbox, la passerelle sélectionne un exécuteur éligible et lui envoie une requête de placement. L’exécuteur résout la spécification du bac à sable selon sa politique, puis crée la sandbox à partir du résultat obtenu. L’exécuteur accepte le placement dès qu’il a créé la sandbox, sans attendre son démarrage : le client reçoit donc l’ID de la sandbox alors que celle-ci est encore en cours de démarrage.

```mermaid theme={"system"}
sequenceDiagram
    participant Client as Python SDK / REST API
    participant GW as Gateway<br/>api.cwsandbox.com
    participant Runner as Managed runner
    participant SB as Sandbox

    Client->>GW: StartSandbox (spec)
    GW->>GW: Scheduler picks an eligible runner
    GW->>Runner: PlacementRequest
    Runner->>Runner: Merge spec with policy defaults, check constraints
    alt Request fits the policy
        Runner->>SB: Create sandbox from resolved spec
        Runner-->>GW: PlacementResponse (accepted)
        GW-->>Client: sandbox_id, status CREATING or PENDING
        Note over Client,SB: Startup continues asynchronously
        SB-->>Runner: Container starts or fails
        Runner-->>GW: Status update
        loop Until RUNNING or a terminal state
            Client->>GW: Get sandbox (sandbox_id)
            GW-->>Client: Current status
        end
    else Request violates a constraint
        Runner-->>GW: Rejected, with the constraint that failed
        GW-->>Client: Error naming what was refused
    end
```

Une réponse de démarrage réussie signifie que l’exécuteur a accepté la sandbox, et non que la sandbox est déjà en mesure d’exécuter des commandes. Avant d’utiliser la sandbox, attendez qu’elle atteigne l’état `RUNNING` ou interrogez son statut jusqu’à ce que ce soit le cas. Si le démarrage échoue, la sandbox passe à l’état `FAILED`. Elle peut aussi atteindre `COMPLETED` avant `RUNNING` si sa commande principale se termine rapidement avec le statut 0. Gérez ces deux états terminaux. La méthode `wait()` du SDK Python interroge le statut à votre place, et les opérations telles que `exec()` attendent l’état `RUNNING` avant de s’exécuter. Voir [Cycle de vie d’une sandbox](/fr/products/sandboxes/client/guides/sandbox-lifecycle#wait-for-a-sandbox).

C’est le cas de rejet que les utilisateurs remarquent. Comme l’erreur indique la contrainte non respectée, un utilisateur qui demande quelque chose que le cluster n’autorise pas sait ce qu’il doit modifier ou ce qu’il doit demander à un administrateur, sans avoir à connaître la posture à l’avance.

<h3 id="data-plane-running-sandbox-operations">
  Plan de données : exécution des opérations sur la sandbox
</h3>

Une fois la sandbox placée, les appels client ultérieurs (`exec`, opérations sur les fichiers, arrêt) transitent par la passerelle jusqu’à l’exécuteur qui détient la sandbox, puis de là jusqu’à la sandbox elle-même.

```mermaid theme={"system"}
sequenceDiagram
    participant Client as Python SDK / REST API
    participant GW as Gateway<br/>api.cwsandbox.com
    participant Runner as Owning runner
    participant SB as Sandbox

    Client->>GW: Exec, file ops, stop
    GW->>Runner: Forward to sandbox owner
    Runner->>SB: Apply
    SB-->>Runner: Result
    Runner-->>GW: Response
    GW-->>Client: Response
```

Les opérations d’exécution, de journalisation et sur les fichiers peuvent également contourner complètement la passerelle. Le SDK Python privilégie une connexion mTLS directe entre le client et le sandbox, et se rabat sur le chemin via la passerelle illustré ci-dessus lorsque l’accès direct n’est pas disponible. Les appels liés au cycle de vie et à la gestion passent toujours par la passerelle. Voir [Connexions directes aux sandbox](/fr/products/sandboxes/client/guides/direct-connections).

<h2 id="control-plane-resources">
  Ressources du plan de contrôle
</h2>

Le plan de contrôle expose les runners en tant que ressource d’administration. Une politique n’a pas de point de terminaison propre : on y accède par l’intermédiaire du runner auquel elle est associée.

| Ressource | Points de terminaison | Rôle |
| - | - | - |
| Runners gérés | `POST/GET/PATCH/DELETE /v1/sandbox/managedRunners`, `POST .../applyAvailableUpdate` | Déployer, interroger, mettre à jour et mettre hors service des runners. Définir la politique associée à un runner. Déclencher à la demande la mise à jour d’un runner. |

L’[aperçu de l’API du plan de contrôle](/fr/products/sandboxes/reference/control-plane-api) présente l’authentification, les masques de champs, les heartbeats ainsi que la structure des requêtes et des réponses de ces points de terminaison.

<h2 id="see-also">
  Voir aussi
</h2>

* [Utiliser votre propre infrastructure de calcul](/fr/products/sandboxes/get-started-cks) : activer un runner et lancer une sandbox.
* [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.
* [Déployer et gérer un runner](/fr/products/sandboxes/operations/managed-runners) : le cycle de vie des runners gérés.
* [Aperçu de l’API du plan de contrôle](/fr/products/sandboxes/reference/control-plane-api) : l’authentification, les masques de champs et la structure des requêtes et des réponses de chaque point de terminaison.
* [Protobuf](/fr/products/sandboxes/reference/protos) : l’hôte qui fournit chaque service, et comment générer un client à partir du module Protobuf publié.