直接サンドボックス接続

このページの例では、CWSANDBOX_API_KEY に設定した CoreWeave API アクセストークンを使用します。Forge APIキーによる認証については、はじめにを参照してください。CKS の要件については、配置モードを参照してください。直接サンドボックス接続では、exec、ログ、ファイル操作を CoreWeave Sandboxes ゲートウェイ経由で中継するのではなく、相互 TLS (mTLS) でクライアントからサンドボックスへ直接送信します。ゲートウェイのホップを排除することで、サンドボックスとの間で大量のデータをやり取りするワークロードのレイテンシーを低減し、スループットを向上させます。サンドボックスの起動、サンドボックスの一覧表示、停止など、ライフサイクルおよび管理操作は常に CoreWeave Sandboxes API を使用します。直接接続は、すでに実行中のサンドボックスに対するデータ操作にのみ適用されます。このページは、cwsandbox Python SDK を使用してサンドボックスを起動および管理する開発者向けです。データ操作のトランスポートポリシーの選択方法、SDK が直接接続を確立する方法、および操作が使用したトランスポートを確認する方法について説明します。

概要

DataPlaneMode 列挙型は、データ操作のトランスポートポリシーを設定します。明示的に指定しない限り SDK は AUTO を使用するため、ほとんどの呼び出し元はコードを変更しなくても直接接続を利用できます。

モード	動作	使用する場面
`AUTO`	直接の mTLS 接続を優先し、直接アクセスが利用できない場合は透過的にゲートウェイへフォールバックします。	デフォルトです。トランスポートを 1 つに固定する必要がない限り、このモードを使用してください。
`DIRECT`	直接の mTLS 接続を必須とし、接続を確立できない場合は送出される例外です。	ご利用の環境で直接接続が機能するかを検証する場合。
`GATEWAY`	データ操作を常にゲートウェイ経由でルーティングします。	直接トランスポートが原因でないことを切り分ける必要がある場合の、確実なロールバック手段として。

トランスポートポリシーを設定する

単一のサンドボックスに対してトランスポートポリシーを設定するには、data_plane_mode を Sandbox.run() に渡します。サンドボックスのグループに対して設定するには、data_plane_mode を SandboxDefaults に渡します。

from cwsandbox import DataPlaneMode, Sandbox, SandboxDefaults

# AUTO はデフォルトです: direct を優先し、gateway にフォールバックします。
with Sandbox.run() as sandbox:
    result = sandbox.exec(["echo", "hello"]).result()
    print(result.stdout)

# direct パスを要求します。接続性の検証時に便利です。
with Sandbox.run(data_plane_mode=DataPlaneMode.DIRECT) as sandbox:
    print(sandbox.read_file("/etc/hostname").result().decode())

# これらのデフォルトを使用するすべてのサンドボックスで gateway パスを強制します。
defaults = SandboxDefaults(data_plane_mode=DataPlaneMode.GATEWAY)
with Sandbox.run(defaults=defaults) as sandbox:
    print(sandbox.exec(["echo", "gateway"]).result().stdout)

直接接続の確立方法

サンドボックスが実行中で、最初のデータ操作を発行すると、SDK はメモリ内に P-256 秘密鍵を生成し、証明書署名リクエストのみを CoreWeave Sandboxes API に送信します。API はそのサンドボックスにスコープされた証明書を返し、SDK はそれを使用してサンドボックス自体への mTLS 接続を開きます。この交換の 2 つのプロパティは、認証情報について考える際に重要です。

秘密鍵はクライアントプロセスから決して離れません。SDK は証明書署名リクエストを送信し、鍵自体は送信しません。
API Bearer token はサンドボックスのデータエンドポイントに送信されることはありません。サンドボックスは証明書のみでクライアントを認証します。

SDK は認証情報を遅延作成するため、ライフサイクル Call のみを実行するサンドボックスはそれらを要求しません。SDK は独自に短いセッション有効期間を課すのではなく、サーバーが発行する証明書の有効期限切れを使用します。

タイミングとフォールバック

AUTO と DIRECT では、待機時間と、セットアップが時間内に完了しなかった場合の動作が異なります。

AUTO では、認証情報の発行とチャンネルの準備完了で合計 1 秒の予算を共有します。この予算を使い切ると、操作はゲートウェイ経由で続行され、SDK は 30 秒待機してから再び直接接続を試みます。フォールバックは透過的に行われるため、操作は問題なく成功します。
DIRECT では、接続のセットアップに最大 10 秒が割り当てられ、フォールバックは行われません。セットアップが完了しない場合、操作はエラーを送出します。

接続の再利用

SDK は、プロセス全体でアイドル状態の直接チャンネルをプールとして保持し、上限を 64 に設定しています。プールを制限することで、多数の非アクティブなサンドボックスオブジェクトを保持するプログラムが、サンドボックスごとに 1 つのソケットを保持しないようにしています。実行中のストリームは、開始したチャンネルを保持します。チャンネルが古いとマークされると、既存のストリームはそのチャンネルでドレインされ、新しい Call は置き換えチャンネルを作成します。

操作が使用したトランスポートを検証する

直接接続性が環境から機能することを確認するには、DIRECT の下で操作を実行します。このモードはフォールバックしないため、正常に返された操作は直接トランスポートを使用したことになります。接続を確立できない操作は、ゲートウェイをサイレントに使用する代わりにエラーを送出します。

from cwsandbox import DataPlaneMode, Sandbox

with Sandbox.run(data_plane_mode=DataPlaneMode.DIRECT) as sandbox:
    result = sandbox.exec(["echo", "direct"]).result()
    print(result.stdout)

この操作で送出される例外が発生した場合、同じ Call が GATEWAY 下で成功する一方で、サンドボックスのデータエンドポイントがネットワークから到達できない状態です。Call 発行元を AUTO のままにしておくと、ゲートウェイ経由で動作し続けながら、クライアントとサンドボックス間の外向き通信制限を確認できます。

サンドボックス

サンドボックスを使用する

サンドボックスの管理

リファレンス

直接サンドボックス接続

概要

トランスポートポリシーを設定する

直接接続の確立方法

タイミングとフォールバック

接続の再利用

操作が使用したトランスポートを検証する

関連項目

​概要

​トランスポートポリシーを設定する

​直接接続の確立方法

​タイミングとフォールバック

​接続の再利用

​操作が使用したトランスポートを検証する

​関連項目

概要

トランスポートポリシーを設定する

直接接続の確立方法

タイミングとフォールバック

接続の再利用

操作が使用したトランスポートを検証する

関連項目