cwsandbox Python SDK を使用してサンドボックスを起動および管理する開発者向けです。データ操作のトランスポートポリシーの選択方法、SDK が直接接続を確立する方法、および操作が使用したトランスポートを確認する方法について説明します。
認証方式を選択する
これらの例は、セクションで CKS が指定されていない限り、サーバーレスキャパシティ上で実行されます。サンドボックスを所有するアカウントの認証情報を選択してください。キーまたはトークンの取得方法については、認証情報の選択と取得を参照してください。 インストールコマンドは、有効化した Python 仮想環境で実行してください。 使用する認証情報のタブにある Python コードをsandbox_auth.py として、このページで実行する Python スクリプトと同じディレクトリに保存します。このファイルに保存されるのは認証方式の選択であり、認証情報そのものではありません。各例ではこのファイルから AUTH をインポートし、新しいサンドボックスまたはセッションを作成するたびに明示的に渡します。
- Forge API キー
- CoreWeave API アクセストークン
SDK の W&B 認証方式で Forge APIキーを使用します。
sandbox_auth.py
SandboxDefaults で placement_mode="cks" を設定します。auth=AUTH を指定してセッションを作成すると、そのセッションが所有するサンドボックスも認証されます。サンドボックスへの再接続、一覧表示、クリーンアップの際も、同じ認証情報を使用してください。
概要
DataPlaneMode 列挙型は、データ操作のトランスポートポリシーを設定します。明示的に指定しない限り SDK は AUTO を使用するため、ほとんどの呼び出し元はコードを変更しなくても直接接続を利用できます。
トランスポートポリシーを設定する
単一のサンドボックスに対してトランスポートポリシーを設定するには、data_plane_mode を Sandbox.run() に渡します。サンドボックスのグループに対して設定するには、data_plane_mode を SandboxDefaults に渡します。
直接接続の確立方法
サンドボックスが実行中で、最初のデータ操作を発行すると、SDK はメモリ内に P-256 秘密鍵を生成し、証明書署名リクエストのみを CoreWeave Sandboxes API に送信します。API はそのサンドボックスにスコープされた証明書を返し、SDK はそれを使用してサンドボックス自体への mTLS 接続を開きます。 この交換の 2 つのプロパティは、認証情報について考える際に重要です。- 秘密鍵はクライアントプロセスから決して離れません。SDK は証明書署名リクエストを送信し、鍵自体は送信しません。
- API Bearer token はサンドボックスのデータエンドポイントに送信されることはありません。サンドボックスは証明書のみでクライアントを認証します。
タイミングとフォールバック
AUTO と DIRECT では、待機時間と、セットアップが時間内に完了しなかった場合の動作が異なります。
AUTOでは、認証情報の発行とチャンネルの準備完了で合計 1 秒の予算を共有します。この予算を使い切ると、操作はゲートウェイ経由で続行され、SDK は 30 秒待機してから再び直接接続を試みます。フォールバックは透過的に行われるため、操作は問題なく成功します。DIRECTでは、接続のセットアップに最大 10 秒が割り当てられ、フォールバックは行われません。セットアップが完了しない場合、操作はエラーを送出します。
接続の再利用
SDK は、プロセス全体でアイドル状態の直接チャンネルをプールとして保持し、上限を 64 に設定しています。プールを制限することで、多数の非アクティブなサンドボックス オブジェクト を保持するプログラムが、サンドボックスごとに 1 つのソケットを保持しないようにしています。 実行中のストリームは、開始したチャンネルを保持します。チャンネルが古いとマークされると、既存のストリームはそのチャンネルでドレインされ、新しい Call は置き換えチャンネルを作成します。操作が使用したトランスポートを検証する
直接接続性が環境から機能することを確認するには、DIRECT の下で操作を実行します。このモードはフォールバックしないため、正常に返された操作は直接トランスポートを使用したことになります。接続を確立できない操作は、ゲートウェイをサイレントに使用する代わりにエラーを送出します。
GATEWAY 下で成功する一方で、サンドボックスのデータエンドポイントがネットワークから到達できない状態です。Call 発行元を AUTO のままにしておくと、ゲートウェイ経由で動作し続けながら、クライアントとサンドボックス間の外向き通信制限を確認できます。
関連項目
- サンドボックスのアーキテクチャ: コントロールプレーン、ゲートウェイ、ランナーの連携について説明します。
- 実行: サンドボックスでコマンドを実行する方法を説明します。
- ファイル操作: サンドボックスでファイルを読み書きする方法を説明します。
-
サンドボックスの設定:
SandboxDefaultsとSandbox.run()で設定できるその他のオプションについて説明します。