> ## 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 を使用すると、組織に登録されているランナーの一覧表示や、各ランナーが公開しているハードウェア情報の読み取りに加え、サンドボックスを配置する前にリアルタイムのキャパシティを確認できます。

ランナーは CKS クラスター内のデプロイメントです。CoreWeave のマネージドコントロールプレーンに登録され、クラスターのコンピュートをサンドボックスプラットフォームに橋渡しします。そのため、ランナーの機能は背後にあるクラスターのハードウェアに依存します。

ディスカバリーは CKS への配置にのみ適用されます。サーバーレスのサンドボックスはお客様が所有するランナー上で実行されるわけではないため、検出する対象がありません。必要なサンドボックスの内容を指定するだけで、プラットフォームが配置を行います。[サンドボックスの配置](/ja/products/sandboxes/placement)を参照してください。

ディスカバリーで報告されるのはランナーの能力であり、何が許可されているかではありません。個々のサンドボックスが要求できる内容は、ランナーに設定されたポリシーによって制限されます。このポリシーは管理者が作成します。[ポリシーの概要](/ja/products/sandboxes/profiles/profiles)を参照してください。

<Note>
  **プロフィールから移行する場合:** クライアントは `Profile`、`list_profiles()`、`get_profile()`、`ProfileNotFoundError` をエクスポートしなくなりました。`profile_names` と `profile_ids` は `Sandbox`、`Session`、およびそれらの `list()` メソッドのパラメーター名として残っていますが、値を渡すと `TypeError` が送出されます。代わりに `runner_ids` でランナーを指定してください。ガバナンスモデルはプロフィールからポリシーに置き換わりました。ポリシーはユーザーが選択するものではありません。[ポリシーの概要](/ja/products/sandboxes/profiles/profiles)を参照してください。
</Note>

<h2 id="list-runners">
  ランナーの一覧表示
</h2>

`list_runners()` は、使用中の認証情報で参照できるすべてのランナーを返します。

```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` には組み込みの表現形式があり、ランナー ID、所有元の
組織、健全性、人間が読みやすい単位で表した CPU とメモリ、GPU 数、およびランナーが強制できる
サービスの可視性を出力します。

出力例:

```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">
  ランナーの機能を読み取る
</h2>

各ランナーは、自身のノードに搭載されたハードウェアを公開しています。これらの属性を読み取り、作成したいサンドボックスの要件を満たす
ランナーを検索します。

```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` には、GPU リクエストの `type` キーにそのまま渡す文字列が格納されています。
照合では大文字と小文字が区別されるため、`B200` と `b200` は別のタイプとして扱われます。
[GPU サンドボックスを実行する](/ja/products/sandboxes/gpu-sandboxes)を参照してください。

`max_gpu_count` はランナーが報告する GPU キャパシティの合計値であり、サンドボックスごとの上限ではありません。1 つのサンドボックスがリクエストできる
GPU 数の上限は、ランナーのポリシーの `maxGpuCount` と、
単一ノード上の空き GPU 数によって決まります。

<h3 id="runner-attributes">
  ランナーの属性
</h3>

`Runner` には次の属性があります。

| 属性 | タイプ | 説明 |
| - | - | - |
| `runner_id` | `str` | 組織内でのランナーの識別子です。グローバルに一意ではありません。 |
| `organization_id` | `str` | ランナーを所有する組織です。 |
| `runner_group_id` | `str` | ランナーが属するグループです。 |
| `tags` | `tuple[str, ...]` | ランナーに付与されたタグです。 |
| `healthy` | `bool` | ランナーが現在正常かどうかを示します。 |
| `is_shared` | `bool` | ランナーが共有組織に属する場合は `True` です。 |
| `connected_at` | `datetime` | ランナーが接続した日時です (UTC のタイムゾーン情報付き datetime)。 |
| `max_cpu_millicores` | `int` | 報告された CPU キャパシティの合計です (単位: ミリコア)。 |
| `max_memory_bytes` | `int` | 報告されたメモリキャパシティの合計です (単位: バイト)。 |
| `max_gpu_count` | `int` | 報告された GPU キャパシティの合計です。 |
| `supported_gpu_types` | `tuple[str, ...]` | ランナーのノードに搭載されている GPU のタイプです。 |
| `supported_architectures` | `tuple[str, ...]` | ランナーがサポートする CPU アーキテクチャー (`amd64` など) です。 |
| `supports_privileged` | `bool` | 特権コンテナーが許可されているかどうかを示します。 |
| `available_storage_classes` | `tuple[str, ...]` | クラスターで利用可能な Kubernetes ストレージクラスです。 |
| `supported_service_visibilities` | `tuple[str, ...]` | ランナーが強制できるサービスの可視性 (`public`、`private`、`custom` のいずれか) です。[`ServiceVisibility`](/ja/products/sandboxes/client/ref/networking/services#servicevisibility) を参照してください。 |
| `resources` | `RunnerResources \| None` | 現在のリソース可用性です。ランナーが報告しない場合は `None` になります。 |

`max_*` の値が `0` であっても、リソースがないとは限らず、ランナーがそのキャパシティを開示または報告していないだけの場合があります。
共有ランナーではキャパシティが非開示のため `0` が返されます。また、CPU とメモリの値には予約キャパシティが含まれない場合があります。

<h2 id="check-live-capacity">
  リアルタイムのキャパシティを確認する
</h2>

デフォルトでは、`list_runners()` は機能データのみを返します。
`include_resources=True` を渡すと、`Runner.resources` にリアルタイムの可用性が格納されます。
`format_bytes()` と `format_cpu()` を使用すると、値を人間が読みやすい単位で出力できます。

```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` は `None` になります。値を読み取る前に
`None` かどうかを確認してください。

<h3 id="runnerresources-attributes">
  RunnerResources の属性
</h3>

`RunnerResources` オブジェクトには次の属性があります。

| 属性 | タイプ | 説明 |
| - | - | - |
| `available_cpu_millicores` | `int` | 予約されていない CPU (ミリコア単位)。 |
| `available_memory_bytes` | `int` | 予約されていないメモリ (バイト単位)。 |
| `available_gpu_count` | `int` | 予約されていない GPU の数。 |
| `running_sandboxes` | `int` | ランナー上で現在実行中のサンドボックスの数。 |

<h2 id="filter-the-list">
  リストをフィルターする
</h2>

フィルターを組み合わせて、ワークロードを受け入れ可能なランナーにリストを絞り込みます。
次の呼び出しは、指定した GPU タイプを搭載し、空き GPU が 2 基以上ある正常なランナーを
返します。`[GPU-TYPE]` は `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")
```

ディスカバリーサービスは `runner_group_id`、`gpu_type`、`architecture`、
`healthy_only`、`service_visibility` を適用します。3 つの
`min_available_*` フィルターは、結果を受信した後にクライアント側で適用されます。これら 3 つのフィルターを指定すると `include_resources` が自動的に有効になり、リソースデータを報告しないランナーは除外されます。
そのため、これらのフィルターを通過した結果では、`resources` に常に値が設定されています。

<h3 id="parameters">
  パラメーター
</h3>

`list_runners()` では次のパラメーターを指定できます。いずれもキーワード専用引数です。

| パラメーター | タイプ | 説明 |
| - | - | - |
| `auth` | `AuthConfig \| None` | このリクエストで使用する認証方式、解決済みヘッダー、またはプロバイダー。 |
| `runner_group_id` | `str \| None` | 結果を指定したランナーグループに限定します。 |
| `gpu_type` | `str \| None` | 指定した GPU タイプをサポートするランナーのみを返します。 |
| `architecture` | `str \| None` | 指定した CPU アーキテクチャーをサポートするランナーのみを返します。 |
| `healthy_only` | `bool` | 正常なランナーのみを返します。デフォルトは `False` です。 |
| `include_resources` | `bool` | 各ランナーの現在のリソース可用性を結果に含めます。デフォルトは `False` です。 |
| `min_available_cpu_millicores` | `int \| None` | 予約されていない CPU ミリコア数の最小値。指定すると `include_resources` が自動的に有効になります。 |
| `min_available_memory_bytes` | `int \| None` | 予約されていないメモリバイト数の最小値。指定すると `include_resources` が自動的に有効になります。 |
| `min_available_gpu_count` | `int \| None` | 予約されていない GPU 数の最小値。指定すると `include_resources` が自動的に有効になります。 |
| `service_visibility` | `str \| None` | 指定したサービスの可視性 (`public`、`private`、または `custom`) を強制できるランナーのみを返します。 |

<h2 id="get-a-single-runner">
  単一のランナーを取得する
</h2>

`get_runner()` は、ランナー ID と、そのランナーを所有する組織を受け取ります。ランナー ID はグローバルではなく組織内でのみ
一意であるため、両方の指定が必須です。この呼び出しでは常に完全な詳細が返されますが、リソース可用性が含まれるのは
自分の組織が所有するランナーの場合のみです。`[RUNNER-ID]` と `[ORGANIZATION-ID]` を、対象のランナーと
それを所有する組織の ID に置き換えてください：

```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}")
```

一覧で取得した各ランナーには、それぞれ固有の `organization_id` が含まれています。そのため、前の結果で見つけたランナーを検索するときは、
`runner.organization_id` を渡してください。

<h2 id="create-a-sandbox-on-a-discovered-runner">
  検出したランナーでサンドボックスを作成する
</h2>

`placement_mode="cks"` を設定し、選択したランナーを `runner_ids` に渡します。
`[GPU-TYPE]` は `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)
```

`runner_ids` を指定しない場合、CKS への配置では、組織内の条件を満たす任意のランナーを使用できます。
`runner_ids` は、サーバーレスへの配置、および
`placement_spillover="serverless_then_cks"` とは併用できません。

<h3 id="apply-a-runner-to-every-sandbox-in-a-session">
  Session 内のすべてのサンドボックスにランナーを適用する
</h3>

`SandboxDefaults` を使用すると、Session 内のすべてのサンドボックスを同じランナーに割り当てることができます。

```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)
```

サンドボックスのその他のオプションについては、
[サンドボックスの設定ガイド](/ja/products/sandboxes/client/guides/sandbox-configuration)を参照してください。

<h2 id="error-reference">
  エラーリファレンス
</h2>

ディスカバリーの 呼び出し では、次の例外が発生する場合があります。

| 例外 | 原因 |
| - | - |
| `RunnerNotFoundError` | 指定された `runner_id` と `organization_id` に一致するランナーが存在しません。 |
| `DiscoveryValidationError` | ディスカバリーリクエストがフィールド単位の検証に失敗しました。 |
| `DiscoveryError` | ディスカバリー操作中にネットワークエラーまたはサービスエラーが発生しました。上記 2 つの例外の基底クラスです。 |
| `CWSandboxAuthenticationError` | 認証情報が無効であるか、指定されていません。 |

`runner_id` または `organization_id` が空の場合、`get_runner()` はリクエストを送信する前に `ValueError`
を送出します。

例外の階層全体については、
[例外リファレンス](/ja/products/sandboxes/client/ref/exceptions/exceptions)を参照してください。
一般的なトラブルシューティング手順については、
[Sandboxes のサポート記事](/ja/support/sandboxes)を参照してください。