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

# サンドボックスのアーキテクチャ

> 1 つ以上の CKS クラスターにわたるランナー、ポリシー、ゲートウェイの連携の仕組み。

このページでは、ランナーのデプロイ、ポリシーの作成、マルチクラスターへのロールアウトの計画を担当する管理者向けに、CoreWeave Sandboxes の各構成要素がどのように連携するかを説明します。

CoreWeave のサンドボックスは、ユーザーが管理する 2 つのリソース(**マネージドランナー**と**サンドボックス**)、各ランナーに付随する**ポリシー**、そしてすべてのサンドボックスリクエストを仲介する CoreWeave 運用のインフラストラクチャー(**ゲートウェイ**)で構成されます。これらの構成要素は、設定用の**コントロールプレーン**とトラフィック用の**データプレーン**という 2 つのサービス層の背後に配置され、有効化した任意の数の CKS クラスターにまたがって動作します。

ランナーの有効化からサンドボックスの起動までの手順については、[独自のコンピュートを使用する](/ja/products/sandboxes/get-started-cks)を参照してください。サンドボックスがポリシーに照らしてどのように解決されるかについては、[ポリシーの概要](/ja/products/sandboxes/profiles/profiles)を参照してください。

<h2 id="sandbox-resources">
  サンドボックスのリソース
</h2>

* **マネージドランナー**: お客様の CKS クラスターのいずれかで動作する、CoreWeave が運用するコンポーネントです。ランナーは、そのクラスター上でサンドボックスの配置、監視、破棄を行います。1 つのクラスターでホストできるマネージドランナーは最大 1 つで、CoreWeave は選択された `RELEASE_CHANNEL_STABLE` または `RELEASE_CHANNEL_RAPID` チャンネルに従ってランナーを常に最新の状態に保ちます。
* **ポリシー**: クラスター上のサンドボックスが要求できる内容と、デフォルトで割り当てられる内容を定めます。ポリシーは独立したリソースではなく、専用のエンドポイントも持ちません。ポリシーはランナーのフィールドの 1 つであるため、各クラスターに適用されるポリシーは常に 1 つだけです。ポリシーの作成方法については、[サンドボックスポリシーを設定する](/ja/products/sandboxes/profiles/configure)を参照してください。
* **サンドボックス**: お客様のクラスター上で実行される、分離されたワークロードです。サンドボックスは、必要なイメージ、コンピュート、ネットワークアクセス、有効期間をすべて自ら宣言します。サンドボックスは [Python クライアント](/ja/products/sandboxes/client)を使用してオンデマンドで作成します。

**ゲートウェイ**は、お客様が作成または所有するリソースではありません。`api.cwsandbox.com` で提供される CoreWeave のサービスで、クライアントからのすべての呼び出しを認証し、サンドボックスをホストできるランナーを選択して、クライアントと各サンドボックスを所有するランナーとの間でトラフィックを中継します。サンドボックスの実行開始後は、ゲートウェイを経由せずに直接 mTLS 接続を使用してデータ操作を行うこともできます。詳しくは、[サンドボックスへの直接接続](/ja/products/sandboxes/client/guides/direct-connections)を参照してください。

<h3 id="key-constraints">
  主な制約
</h3>

* 1 つのクラスターでホストできるマネージドランナーは最大 1 つで、各ランナーには必ず 1 つのポリシーが設定されます。つまり、1 つのクラスターは 1 つのポリシーによって管理されます。異なるポスチャーでサンドボックスを実行するには、別のクラスターにランナーをデプロイし、そのランナーに専用のポリシーを設定してください。
* ポリシーは必須です。空のポリシーも有効で、制限のない完全に許可されたポスチャーを宣言します。これにより、クラスターのポスチャーが意図せず継承されることはなく、常に明示的に定義されます。
* ポリシーでは、サンドボックスのライフタイムのデフォルト値を指定できます。最大値の 30 日はプラットフォームによって強制されます。
* ポリシーの変更は、変更後に作成されたサンドボックスにのみ適用されます。実行中のサンドボックスには、起動時に解決されたポリシーが引き続き適用されます。
* クラスター内でユーザー単位やチーム単位のスコープを設定することはできません。ポリシーは、作成者にかかわらず、そのクラスターに配置されたすべてのサンドボックスに適用されます。

<h2 id="resource-relationships">
  リソース間の関係
</h2>

ランナーは両者をつなぐ役割を担います。ランナーは自身のクラスターを管理するポリシーを保持し、すべてのサンドボックスをそのクラスター上に配置します。サンドボックスは必要なリソースを宣言し、ポリシーはそのリクエストを許可するかどうかを判断します。

```mermaid theme={"system"}
graph LR
    R[マネージドランナー]
    PL[ランナーのポリシー]
    S[サンドボックスの spec]
    P[サンドボックス]

    R -->|保持します| PL
    S -->|必要なものを宣言します| PL
    PL -->|許可または拒否し, その後構成を調整します| P
    R -->|配置します| P
```

ランナーは、サンドボックスの spec をポリシーのデフォルトにマージしたうえで、その結果を制約に照らして検証します。違反がある場合は、黙って範囲を狭めることはせずに拒否し、拒否した内容をエラーに明示します。詳しくは [ポリシーの概要](/ja/products/sandboxes/profiles/profiles#how-a-sandbox-resolves-against-a-policy) を参照してください。

<h2 id="multi-cluster-scope">
  マルチクラスターのスコープ
</h2>

各クラスターには、それぞれ独自のランナーとポリシーがあります。ユーザーがこのトポロジを意識する必要はありません。必要な設定のサンドボックスを SDK にリクエストするだけで、ゲートウェイがそのリクエストを受け入れるポリシーを持つクラスターへルーティングします。

```mermaid theme={"system"}
graph TB
    Client[クライアント / Python SDK]
    GW[ゲートウェイ]

    subgraph C3 [CKS クラスター C]
        direction TB
        R3[マネージドランナー + ポリシー]
        S3A[サンドボックス]
        S3B[サンドボックス]
        R3 --> S3A
        R3 --> S3B
    end
    subgraph C2 [CKS クラスター B]
        direction TB
        R2[マネージドランナー + ポリシー]
        S2A[サンドボックス]
        R2 --> S2A
    end
    subgraph C1 [CKS クラスター A]
        direction TB
        R1[マネージドランナー + ポリシー]
        S1A[サンドボックス]
        S1B[サンドボックス]
        R1 --> S1A
        R1 --> S1B
    end

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

CKS での配置では、ゲートウェイが組織内のクラスター全体からコンピュートを選択します。ランナー ID による制限がない場合は、空き容量があり、かつランナーのポリシーがサンドボックスのリクエストを許可するクラスターが選択されます。

ポスチャーはクラスターごとに定義されるため、許容範囲の広い環境と制限の厳しい環境の両方を必要とするチームは、1 つのクラスターで 2 つの設定を使用するのではなく、2 つのクラスターを運用します。

<h2 id="how-sandboxes-launch">
  サンドボックスの起動の仕組み
</h2>

リソースは 2 つのサービス面を経由します。`api.coreweave.com` の **コントロールプレーン**では、ランナーと各ランナーに適用するポリシーを定義します。`api.cwsandbox.com` の **データプレーン**では、サンドボックスを起動して操作します。この分離は、障害やアクセス制御を検討する際に重要です。コントロールプレーンの障害はランナーやポリシーの編集を妨げますが、すでに実行中のサンドボックスには影響しません。一方、データプレーンの障害は処理中のサンドボックスのトラフィックに影響しますが、コントロールプレーンに保存されている設定には影響しません。

<h3 id="control-plane-one-time-setup">
  コントロールプレーン: 初回設定
</h3>

管理者は CoreWeave Intelligent CLI または REST API を使用して、CKS クラスターにランナーをデプロイし、そのランナーに適用するポリシーを設定します。その後、コントロールプレーンがクラスター内にランナーをデプロイし、ランナーはハートビートを通じて状態を報告します。

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

このステップはクラスターごとに一度実行し、その後はポリシーを変更するたびに再度実行します。対応するワークフローについては、[サンドボックスポリシーを設定する](/ja/products/sandboxes/profiles/configure)と[ランナーのデプロイと管理](/ja/products/sandboxes/operations/managed-runners)を参照してください。

<h3 id="data-plane-sandbox-launch">
  データプレーン: サンドボックスの起動
</h3>

クライアントがサンドボックスを起動すると、ゲートウェイは条件を満たすランナーを選び、そのランナーに配置リクエストを送信します。ランナーは自身のポリシーに照らしてサンドボックスの spec を解決し、その結果をもとにサンドボックスを作成します。ランナーはサンドボックスの起動完了を待たず、作成した時点で配置を受け入れます。そのため、クライアントはサンドボックスの起動中にサンドボックス ID を受け取ることになります。

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

開始リクエストに対して成功の応答が返っても、それはランナーがサンドボックスを受け付けたことを示すだけで、サンドボックスがすでにコマンドを実行できる状態になったことを意味するわけではありません。サンドボックスを使用する前に、`RUNNING` になるまで待機するか、ポーリングしてください。起動に失敗した場合、サンドボックスは `FAILED` に移行します。また、メインコマンドがステータス 0 ですぐに終了した場合は、`RUNNING` になる前に `COMPLETED` に達することもあります。どちらの終端状態にも対応できるようにしてください。Python SDK の `wait()` はポーリングを自動で行います。また、`exec()` などの操作は、実行前に `RUNNING` になるまで待機します。詳細は [サンドボックスのライフサイクル](/ja/products/sandboxes/client/guides/sandbox-lifecycle#wait-for-a-sandbox) を参照してください。

ユーザーが実際に意識するのは、リクエストが拒否された場合です。エラーには満たされなかった制約が示されるため、クラスターで許可されていない内容を要求したユーザーは、事前にポスチャーを確認しておかなくても、何を変更すればよいか、あるいは管理者に何を依頼すればよいかを把握できます。

<h3 id="data-plane-running-sandbox-operations">
  データプレーン: サンドボックス操作の実行
</h3>

サンドボックスが配置されると、それ以降のクライアントからの 呼び出し (`exec`、ファイル操作、停止) は、ゲートウェイを経由してサンドボックスを管理するランナーに送られ、そこからサンドボックス自体に送られます。

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

Exec、ログ、ファイル操作もゲートウェイを完全に迂回できます。Python SDK はクライアントからサンドボックスへの直接 mTLS 接続を優先し、直接アクセスできない場合は、上記のゲートウェイ経由の経路にフォールバックします。ライフサイクルと管理の 呼び出し は常にゲートウェイを使用します。[サンドボックスへの直接接続](/ja/products/sandboxes/client/guides/direct-connections)を参照してください。

<h2 id="control-plane-resources">
  コントロールプレーンのリソース
</h2>

コントロールプレーンは、管理用のリソースとしてランナーを公開します。ポリシーには専用のエンドポイントがなく、そのポリシーを保持するランナーを通じてアクセスします。

| リソース | エンドポイント | 用途 |
| - | - | - |
| マネージドランナー | `POST/GET/PATCH/DELETE /v1/sandbox/managedRunners`, `POST .../applyAvailableUpdate` | ランナーのデプロイ、クエリ、更新、廃止を行います。ランナーが保持するポリシーを設定します。ランナーの更新をオンデマンドでトリガーします。 |

[コントロールプレーン API の概要](/ja/products/sandboxes/reference/control-plane-api)では、これらのエンドポイントの認証、フィールドマスク、ハートビート、およびリクエストと応答の形式について説明しています。

<h2 id="see-also">
  関連情報
</h2>

* [独自のコンピュートを使用する](/ja/products/sandboxes/get-started-cks): ランナーを有効にして、サンドボックスを起動します。
* [ポリシーの概要](/ja/products/sandboxes/profiles/profiles): サンドボックスがポリシーに基づいて解決される仕組みを説明します。
* [サンドボックスポリシーを設定する](/ja/products/sandboxes/profiles/configure): すべての制約グループを具体例とともに説明します。
* [ランナーのデプロイと管理](/ja/products/sandboxes/operations/managed-runners): マネージドランナーのライフサイクルを説明します。
* [コントロールプレーン API の概要](/ja/products/sandboxes/reference/control-plane-api): 認証、フィールドマスク、および各エンドポイントのリクエストと応答の構造を説明します。
* [Protobuf](/ja/products/sandboxes/reference/protos): 各サービスを提供するホストと、公開されている Protobuf モジュールからクライアントを生成する方法を説明します。