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

# Découvrir les exécuteurs disponibles

> Répertoriez les exécuteurs de votre organisation, consultez le matériel qu’ils annoncent et vérifiez leur capacité disponible.

Utilisez l’API de découverte pour répertorier les exécuteurs enregistrés dans votre organisation, consulter le
matériel annoncé par chacun d’eux et vérifier leur capacité en temps réel avant d’y placer une sandbox.

Un exécuteur est un déploiement dans un cluster CKS. Il s’enregistre auprès du plan de contrôle
managé de CoreWeave et met les ressources de calcul du cluster à la disposition de la plateforme de bacs à sable : les
capacités d’un exécuteur reflètent donc le matériel du cluster sous-jacent.

La découverte s’applique au placement sur CKS. Une sandbox sans serveur ne s’exécute pas sur un exécuteur
qui vous appartient : il n’y a donc rien à découvrir. Décrivez simplement la sandbox souhaitée, et la plateforme
se charge de la placer. Voir [Placement des sandbox](/fr/products/sandboxes/placement).

La découverte indique ce dont un exécuteur est capable, et non ce qu’il autorise. Les ressources qu’une
sandbox peut demander sont limitées par la politique associée à l’exécuteur, définie par un
administrateur. Voir [Aperçu des politiques](/fr/products/sandboxes/profiles/profiles).

<Note>
  **Vous utilisiez les profils ?** Le client n’exporte plus `Profile`,
  `list_profiles()`, `get_profile()` ni `ProfileNotFoundError`. `profile_names` et
  `profile_ids` subsistent en tant que noms de paramètres de `Sandbox`, de `Session` et de leurs méthodes `list()`,
  mais toute valeur transmise lève une exception `TypeError`. Ciblez plutôt un exécuteur avec `runner_ids`.
  Les politiques ont remplacé les profils comme modèle de gouvernance, et vous n’avez pas à en sélectionner
  une : voir [Aperçu des politiques](/fr/products/sandboxes/profiles/profiles).
</Note>

<h2 id="list-runners">
  Lister les exécuteurs
</h2>

`list_runners()` renvoie tous les exécuteurs accessibles avec vos identifiants d’authentification :

```python theme={"system"}
from cwsandbox import AuthStrategy, Runner, list_runners

runners: list[Runner] = list_runners(auth=AuthStrategy.COREWEAVE_API_KEY)

for runner in runners:
    print(runner)
```

`Runner` dispose d’une représentation intégrée qui affiche l’identifiant de l’exécuteur, l’organisation
propriétaire, l’état de santé, le CPU et la mémoire en unités lisibles, le nombre de GPU, ainsi que les
visibilités de service que l’exécuteur peut appliquer.

Exemple de sortie :

```text theme={"system"}
Runner(runner_id='prod-us-east-1', organization_id='1a2b3c4d', healthy=True, cpu=512.0 vCPU, memory=4.0 TiB, gpus=64, visibilities=['public', 'private'])
```

<h2 id="read-runner-capabilities">
  Lire les capacités des exécuteurs
</h2>

Chaque exécuteur expose le matériel dont disposent ses Nœuds. Lisez ces attributs pour trouver un
exécuteur capable de répondre aux besoins de la sandbox que vous souhaitez créer :

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

for runner in list_runners(auth=AuthStrategy.COREWEAVE_API_KEY):
    print(runner.runner_id)
    print(f"  gpu types:     {', '.join(runner.supported_gpu_types) or 'none'}")
    print(f"  max gpus:      {runner.max_gpu_count}")
    print(f"  architectures: {', '.join(runner.supported_architectures)}")
    print(f"  storage:       {', '.join(runner.available_storage_classes)}")
```

`supported_gpu_types` contient les chaînes de caractères exactes à transmettre comme clé `type` d'une requête
GPU. La correspondance est sensible à la casse : `B200` et `b200` ne désignent pas le même type. Voir
[Exécuter un sandbox GPU](/fr/products/sandboxes/gpu-sandboxes).

`max_gpu_count` correspond à la capacité GPU agrégée remontée par l'exécuteur, et non à un plafond par sandbox. Le nombre de
GPU qu'un sandbox peut demander est limité par `maxGpuCount` dans la politique de l'exécuteur et
par les GPU disponibles sur un même nœud.

<h3 id="runner-attributes">
  Attributs de l’exécuteur
</h3>

Un `Runner` possède les attributs suivants :

| Attribut | Type | Description |
| - | - | - |
| `runner_id` | `str` | Identifiant de l’exécuteur au sein de son organisation. N’est pas unique à l’échelle globale. |
| `organization_id` | `str` | Organisation propriétaire de l’exécuteur. |
| `runner_group_id` | `str` | Groupe auquel appartient l’exécuteur. |
| `tags` | `tuple[str, ...]` | Étiquettes associées à l’exécuteur. |
| `healthy` | `bool` | Indique si l’exécuteur est actuellement en bon état de santé. |
| `is_shared` | `bool` | `True` lorsque l’exécuteur appartient à une organisation partagée. |
| `connected_at` | `datetime` | Date et heure de connexion de l’exécuteur, sous forme de datetime UTC avec fuseau horaire. |
| `max_cpu_millicores` | `int` | Capacité CPU agrégée déclarée, en millicœurs. |
| `max_memory_bytes` | `int` | Capacité mémoire agrégée déclarée, en octets. |
| `max_gpu_count` | `int` | Capacité GPU agrégée déclarée. |
| `supported_gpu_types` | `tuple[str, ...]` | Types de GPU dont sont équipés les nœuds de l’exécuteur. |
| `supported_architectures` | `tuple[str, ...]` | Architectures CPU prises en charge par l’exécuteur, par exemple `amd64`. |
| `supports_privileged` | `bool` | Indique si les conteneurs privilégiés sont autorisés. |
| `available_storage_classes` | `tuple[str, ...]` | Classes de stockage Kubernetes disponibles sur le cluster. |
| `supported_service_visibilities` | `tuple[str, ...]` | Visibilités de service que l’exécuteur peut appliquer : `public`, `private` ou `custom`. Voir [`ServiceVisibility`](/fr/products/sandboxes/client/ref/networking/services#servicevisibility). |
| `resources` | `RunnerResources \| None` | Disponibilité des ressources en temps réel, ou `None` si l’exécuteur ne la communique pas. |

Une valeur `max_*` égale à `0` peut signifier que l’exécuteur ne divulgue pas ou ne déclare pas cette capacité, et non
qu’il ne dispose d’aucune ressource. Les exécuteurs partagés renvoient `0`, car leur capacité n’est pas communiquée,
et les valeurs CPU et mémoire peuvent exclure la capacité réservée.

<h2 id="check-live-capacity">
  Vérifier la capacité en temps réel
</h2>

Par défaut, `list_runners()` renvoie uniquement les informations sur les capacités prises en charge. Passez
`include_resources=True` pour renseigner `Runner.resources` avec la disponibilité en temps réel. Utilisez
`format_bytes()` et `format_cpu()` pour afficher les valeurs dans des unités lisibles :

```python theme={"system"}
from cwsandbox import AuthStrategy, format_bytes, format_cpu, list_runners

runners = list_runners(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    include_resources=True,
)

for r in runners:
    print(f"{r.runner_id}  healthy={r.healthy}")
    print(f"  max: {format_cpu(r.max_cpu_millicores)}, {format_bytes(r.max_memory_bytes)}")
    if r.resources:
        free_cpu = format_cpu(r.resources.available_cpu_millicores)
        free_mem = format_bytes(r.resources.available_memory_bytes)
        print(f"  free:  {free_cpu}, {free_mem}, {r.resources.available_gpu_count} GPUs")
        print(f"  running sandboxes: {r.resources.running_sandboxes}")
```

`resources` vaut `None` lorsqu'un exécuteur ne signale pas sa disponibilité. Vérifiez donc que ce champ est défini
avant d'en lire les valeurs.

<h3 id="runnerresources-attributes">
  Attributs de RunnerResources
</h3>

Un objet `RunnerResources` comporte les attributs suivants :

| Attribut | Type | Description |
| - | - | - |
| `available_cpu_millicores` | `int` | CPU non réservé, en millicœurs. |
| `available_memory_bytes` | `int` | Mémoire non réservée, en octets. |
| `available_gpu_count` | `int` | Nombre de GPU non réservés. |
| `running_sandboxes` | `int` | Sandbox en cours d’exécution sur l’exécuteur. |

<h2 id="filter-the-list">
  Filtrer la liste
</h2>

Combinez plusieurs filtres pour restreindre la liste aux exécuteurs capables d'accueillir votre charge de travail. L'appel
suivant renvoie les exécuteurs en bon état de santé qui disposent d'un type de GPU donné et d'au moins
deux GPU disponibles. Remplacez `[GPU-TYPE]` par une valeur de `supported_gpu_types` :

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

runners = list_runners(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    gpu_type="[GPU-TYPE]",
    healthy_only=True,
    min_available_gpu_count=2,
)

for r in runners:
    print(f"{r.runner_id}: {r.resources.available_gpu_count} GPUs free")
```

Le service de découverte applique `runner_group_id`, `gpu_type`, `architecture`,
`healthy_only` et `service_visibility`. Le client applique les trois
filtres `min_available_*` une fois les résultats reçus. Ces trois filtres activent
automatiquement `include_resources` et écartent tout exécuteur qui ne signale aucune donnée de ressources ;
`resources` est donc toujours renseigné dans les résultats qu’ils renvoient.

<h3 id="parameters">
  Paramètres
</h3>

Les paramètres suivants sont disponibles pour `list_runners()`. Ils doivent tous être passés par mot-clé (keyword-only).

| Paramètre | Type | Description |
| - | - | - |
| `auth` | `AuthConfig \| None` | Stratégie d’authentification, en-têtes résolus ou fournisseur à utiliser pour cette requête. |
| `runner_group_id` | `str \| None` | Limiter les résultats à ce groupe d’exécuteurs. |
| `gpu_type` | `str \| None` | Renvoyer uniquement les exécuteurs qui prennent en charge ce type de GPU. |
| `architecture` | `str \| None` | Renvoyer uniquement les exécuteurs qui prennent en charge cette architecture CPU. |
| `healthy_only` | `bool` | Renvoyer uniquement les exécuteurs en bon état de santé. Par défaut : `False`. |
| `include_resources` | `bool` | Inclure la disponibilité des ressources en temps réel pour chaque exécuteur. Par défaut : `False`. |
| `min_available_cpu_millicores` | `int \| None` | Nombre minimum de millicœurs CPU non réservés. Active automatiquement `include_resources`. |
| `min_available_memory_bytes` | `int \| None` | Quantité minimale de mémoire non réservée, en octets. Active automatiquement `include_resources`. |
| `min_available_gpu_count` | `int \| None` | Nombre minimum de GPU non réservés. Active automatiquement `include_resources`. |
| `service_visibility` | `str \| None` | Renvoyer uniquement les exécuteurs capables d’appliquer cette visibilité de service : `public`, `private` ou `custom`. |

<h2 id="get-a-single-runner">
  Obtenir un exécuteur
</h2>

`get_runner()` prend en paramètres un identifiant d’exécuteur et l’organisation à laquelle il appartient. Un identifiant d’exécuteur est
unique au sein de son organisation, et non de manière globale : les deux sont donc requis. L’appel
renvoie toujours les détails complets, mais la disponibilité des ressources n’est incluse que pour les exécuteurs
appartenant à votre organisation. Remplacez `[RUNNER-ID]` et `[ORGANIZATION-ID]` par l’exécuteur
souhaité et l’organisation à laquelle il appartient :

```python theme={"system"}
from cwsandbox import AuthStrategy, RunnerNotFoundError, get_runner

try:
    runner = get_runner(
        "[RUNNER-ID]",
        organization_id="[ORGANIZATION-ID]",
        auth=AuthStrategy.COREWEAVE_API_KEY,
    )
    print(f"{runner.runner_id}  healthy={runner.healthy}")
    if runner.resources:
        print(f"  running sandboxes: {runner.resources.running_sandboxes}")
except RunnerNotFoundError as e:
    print(f"Runner not found: {e.runner_id}")
```

Chaque exécuteur renvoyé par une liste possède son propre `organization_id`. Transmettez donc
`runner.organization_id` lorsque vous récupérez un exécuteur obtenu dans un résultat précédent.

<h2 id="create-a-sandbox-on-a-discovered-runner">
  Créer une sandbox sur un exécuteur découvert
</h2>

Définissez `placement_mode="cks"` et transmettez à `runner_ids` l’exécuteur que vous avez sélectionné. Remplacez
`[GPU-TYPE]` par l’une des valeurs de `supported_gpu_types` :

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

runners = list_runners(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    gpu_type="[GPU-TYPE]",
    min_available_gpu_count=1,
)

if runners:
    with Sandbox.run(
        auth=AuthStrategy.COREWEAVE_API_KEY,
        placement_mode="cks",
        runner_ids=[runners[0].runner_id],
        resources=ResourceOptions(
            requests={"cpu": "2", "memory": "8Gi"},
            limits={"cpu": "2", "memory": "8Gi"},
            gpu={"count": 1, "type": "[GPU-TYPE]"},
        ),
        max_lifetime_seconds=3600,
    ) as sandbox:
        print(sandbox.exec(["nvidia-smi", "-L"]).result().stdout)
```

Sans `runner_ids`, le placement CKS peut utiliser n’importe quel exécuteur éligible de votre organisation.
`runner_ids` est incompatible avec le placement sans serveur ainsi qu’avec
`placement_spillover="serverless_then_cks"`.

<h3 id="apply-a-runner-to-every-sandbox-in-a-session">
  Appliquer un exécuteur à toutes les Sandbox d’une session
</h3>

Utilisez `SandboxDefaults` pour envoyer toutes les Sandbox d’une session vers le même exécuteur :

```python theme={"system"}
from cwsandbox import AuthStrategy, SandboxDefaults, Session, list_runners

runners = list_runners(auth=AuthStrategy.COREWEAVE_API_KEY, healthy_only=True)

if runners:
    defaults = SandboxDefaults(
        auth=AuthStrategy.COREWEAVE_API_KEY,
        placement_mode="cks",
        runner_ids=(runners[0].runner_id,),
    )

    with Session(defaults) as session:
        sb = session.sandbox()
        print(sb.exec(["echo", "running on a discovered runner"]).result().stdout)
```

Pour les autres options de la Sandbox, consultez le
[guide de configuration de la Sandbox](/fr/products/sandboxes/client/guides/sandbox-configuration).

<h2 id="error-reference">
  Référence des erreurs
</h2>

Les appels de découverte peuvent lever les exceptions suivantes.

| Exception | Cause |
| - | - |
| `RunnerNotFoundError` | Aucun exécuteur ne correspond aux `runner_id` et `organization_id` indiqués. |
| `DiscoveryValidationError` | Une requête de découverte n’a pas passé la validation au niveau des champs. |
| `DiscoveryError` | Erreur réseau ou de service survenue lors d’une opération de découverte. Classe de base des deux exceptions ci-dessus. |
| `CWSandboxAuthenticationError` | Identifiants d’authentification non valides ou manquants. |

Lorsque `runner_id` ou `organization_id` est vide, `get_runner()` lève `ValueError`
avant même d’envoyer une requête.

Pour consulter la hiérarchie complète des exceptions, reportez-vous à la
[référence des exceptions](/fr/products/sandboxes/client/ref/exceptions/exceptions).
Pour les étapes de dépannage courantes, consultez les
[articles d’assistance Sandbox](/fr/support/sandboxes).