TypeScript クライアントは、スナップショットのマウント、リストア、実行中のスナップショット、スナップショットの管理をサポートしていますが、停止時のスナップショット には対応していません。
認証を選択する
これらの例は、セクション内で CoreWeave Kubernetes Service (CKS) が指定されていない限り、サーバーレスキャパシティ上で実行されます。サンドボックスを所有するアカウントの認証情報を選択してください。キーまたはトークンの取得方法については、認証情報の選択と取得を参照してください。 使用する言語に対応する設定を、このページから実行するスクリプトと同じ場所に保存してください。Python の例ではsandbox_auth.py から AUTH をインポートします。TypeScript の例では sandbox-client.mts から client をインポートします。これらのファイルは、認証情報そのものを保存せずに認証方法を選択します。Python の場合は、有効化した仮想環境を使用してください。TypeScript の場合は、まず npm install @coreweave/cwsandbox@1.0.0 でクライアントをインストールしてください。
- Forge APIキー
- CoreWeave API アクセストークン
SDK の
wandb インテグレーションで Forge APIキーを使用します。[WANDB-API-KEY] をお使いの APIキーに置き換えてください。- Python
- TypeScript
sandbox_auth.py
SandboxDefaults で placement_mode="cks" を設定してください。TypeScript で CKS を選択するには、CoreWeave トークンを選択し、空でない runnerIds 配列を設定します。auth=AUTH を指定して Python のセッションを作成すると、そのセッションが所有するサンドボックスも認証されます。サンドボックスへの再接続、一覧表示、クリーンアップの際も、同じ認証情報を使用してください。
HTTP API の例では、選択した認証情報タブの Bash コマンドを、リクエストを送信するのと同じシェルで実行してください。選択した認証ヘッダーは sandbox_headers 配列によって渡されます。HTTP による作成例では、サーバーレス配置を使用します。
仕組み
FSS を使用したサンドボックスは、選択したパスに書き込み可能なスクラッチファイルシステムをマウントします。ランナーはこのマウントを直接のオブジェクトストレージマウントではなくEmptyDir でバックアップします。スナップショットとリストアの操作では、そのローカルファイルシステムと組織スコープのオブジェクトストレージバケットの間で tarball をコピーします。
各スナップショットは、サーバーによって割り当てられた fileSystemSnapshotId で識別される FileSystemSnapshot リソースです。スナップショットには 3 つの特性があります。
- 不変: スナップショットを作成すると 1 つのアーカイブが書き込まれます。スナップショットをリストアしてもソースのスナップショットは変更されないため、後でリストアしても常に元のバイトが表示されます。
- 組織スコープ: ご自身の組織で作成されたスナップショットのみをリストアできます。同じ組織内でサンドボックスへのアクセス権を持つチームメンバーは、自身の認証情報を使用してあなたのスナップショットをリストアできます。他の組織のスナップショット ID は見つからないものとして扱われます。
- 独立したライフサイクル: スナップショットはサンドボックスとは別に管理されます。サンドボックスを削除してもそのスナップショットは削除されず、スナップショットを削除してもそれから実行中のサンドボックスには影響しません。
スナップショットマウントでサンドボックスを起動する
サンドボックスは、2 つのファイルシステムソースのいずれかから起動できます。新しく空のスクラッチファイルシステム、または既存のスナップショットのリストアです。新規スクラッチ
新規スクラッチのファイルシステムは空の状態で開始され、後からスナップショットを作成できます。run の実行中に書き込み可能なローカル状態が必要なワークフローで使用してください。- Python
- TypeScript
- HTTP API
スナップショットからリストアする
リストアでは、既存のスナップショットからファイルシステムを起動します。マウントのスナップショットソースにスナップショット ID を設定します。- Python
- TypeScript
- HTTP API
READY である必要があります。まだ CREATING のスナップショットをリストアすると失敗します。スナップショットのステータスと失敗を参照してください。
リストア時間を見込む
スナップショットのリストアでは、サンドボックスでアプリケーションを実行できるようになる前に、アーカイブのコピーと展開が行われます。大規模なモデルのスナップショットでは、リストアに数分かかることがあります。起動時間は次の要素に左右されます。- アーカイブのサイズ
- ファイル数
- 利用可能な CPU
- ローカルストレージ
- ネットワークのスループット
- イメージの起動処理
CREATING だけでは、スケジューリング待ちなのかファイルをリストア中なのかを区別できません。起動に時間がかかっているサンドボックスを削除する前に、status_reason を確認し、サポートへの問い合わせに備えて ID を控えておいてください。固定の期限を設ければ待機時間に上限を設けられますが、経過時間だけではリストアが失敗したと判断することはできません。
スナップショットを撮る
サンドボックスを停止したとき (on stop) と、実行中のサンドボックスから (mid-life) の2つの方法でスナップショットを取得することができます。停止時のスナップショット
シャットダウン時にサンドボックスのファイルシステムを保持するには、停止時のスナップショットを有効にしてサンドボックスを停止します。一時停止と再開は、このパターンで実現します。スナップショットを取得してサンドボックスを停止し、後でそのスナップショットをリストアする新しいサンドボックスを起動します。- Python
- TypeScript
- HTTP API
実行中のスナップショット
実行中のスナップショットは、サンドボックスを停止せずにその状態を取得します。サンドボックスは取得中も取得後も実行を継続します。取得処理では稼働中のファイルシステムをスキャンしますが、この処理はアトミックではありません。そのため、取得中に行われた書き込みは一貫した状態で取得されない可能性があります。一貫した状態が必要な場合は、取得中にアプリケーションの書き込みを一時停止するか、取得前にアプリケーションのチェックポイントを作成してください。- Python
- TypeScript
- HTTP API
snapshot() はデフォルトでスナップショットが READY になるまで待機し、スナップショット ID を返します。スナップショットをフォークする
同じスナップショットを複数のサンドボックスにリストアできます。各スナップショットは不変であるため、リストアされたサンドボックスは同一のバイト列から開始し、書き込みに伴ってそれぞれ異なる状態になります。- 停止時のスナップショット、または実行中のスナップショットを使用して、
READY状態のスナップショットを作成します。 fileSystemSnapshotIdにそのスナップショットを設定して、サンドボックス A を起動します。- 同じ
fileSystemSnapshotIdを使用して、サンドボックス B を起動します。 - サンドボックス A とサンドボックス B への書き込みは、それぞれ独立して状態を変化させます。ソースのスナップショットは変更されないため、後から同じ ID を使用してリストアしても、どちらのフォークへの書き込みも反映されず、元のスナップショットが使用されます。
- Python
- TypeScript
スナップショットを管理する
スナップショットは、作成元のサンドボックスとは独立して一覧表示、取得、削除できます。- Python
- TypeScript
- HTTP API
list_snapshots()、get_snapshot()、delete_snapshot() では、auth 引数で AuthHeaders オブジェクトを渡すこともできます。
スナップショットのステータスと失敗
スナップショットは非同期で作成されます。スナップショットリクエストが成功してfileSystemSnapshotId が返された時点でも、アーカイブの書き込みがまだ続いていることがあり、その後にスナップショットが失敗する場合があります。これは主に、waitForReady が false の場合や、ランナーのアーカイブ処理中にクライアント側でタイムアウトが発生した場合に起こります。
HTTP API で進捗を確認するには、スナップショットを取得して次のフィールドを確認します。
status: ライフサイクル状態。終了状態の値はFILE_SYSTEM_SNAPSHOT_STATUS_READYとFILE_SYSTEM_SNAPSHOT_STATUS_FAILEDです。statusReason:statusがFILE_SYSTEM_SNAPSHOT_STATUS_FAILEDの場合に設定され、失敗の理由を示します。
state と stateReason を読み取ります。対応する状態の値は "ready" と "failed" です。
スナップショットをリストアする前に、GetFileSystemSnapshot をポーリングして、スナップショットが準備完了になるまで待機してください。Python クライアントの snapshot() と get_snapshot() では、結果を待機する場合にこのポーリングが自動で行われます。TypeScript クライアントの snapshot() は、state が "ready" になるまで待機し、スナップショットが失敗した場合は例外をスローします。
失敗したスナップショットリクエストから復旧する
実行中のスナップショットの失敗から復旧する間は、ソースサンドボックスを実行したままにしてください。スナップショットのリモートプロシージャコール (RPC) が失敗しても、それ自体が原因でサンドボックスやそのマウントが削除されることはありません。ただし、Python のサンドボックスのコンテキストマネージャーを抜けたり、終了処理のコードを実行したりすると、サンドボックスが停止する可能性があります。準備完了のスナップショットに保存されていないデータは破棄されることがあります。こうしたクリーンアップが実行される前に、失敗に対処してください。 初回使用時のバケットのプロビジョニングでは、CWSANDBOX_FSS_BUCKET_PROVISIONING が返されることがあります。Python クライアントは、一時的なスナップショット RPC の失敗を、一定の予算の範囲内で再試行します。プロビジョニングがその予算を超えても完了しない場合は、ソースサンドボックスを保持したまま、バックオフを設けて再試行してください。結果が不明確な転送エラーの後に同じリクエストを再試行する場合は、サーバーが重複を排除できるように、明示的に指定した request_id を再利用してください。タイムアウト後にスナップショット ID を取得できている場合は、別のアーカイブをリクエストする前にそのスナップショットの状態を確認してください。FAILED になったスナップショットのデータを再度取得するには、新しいリクエストが必要です。
Python クライアント 1.19.6 では、一時的なスナップショットの失敗では SandboxUnavailableError が発生する場合があり、その他のスナップショットの失敗では SandboxSnapshotError が発生します。ビルドを保持する場合は、両方の例外を処理し、エラーの reason に基づいて再試行すべきかどうかを判断してください。クォータや設定に起因する失敗は、原因に対処せずに再試行しないでください。
次の表は、主な失敗理由とそれぞれの対処法を示しています。
ランナーがアーカイブのアップロードを完了したものの結果を記録できなかった場合、バケット内にオブジェクトが存在していても、スナップショットの行が
FAILED になることがあります。この場合は、スナップショットの作成を再試行してください。
非同期で失敗した場合、プラットフォームは sandbox.file_system_snapshot.async_fail イベントも発行します。これにより、下流の通知システムは、元の呼び出しが返った後に失敗したスナップショットに対応できます。
制限事項
FSS バージョン 1 は、スナップショットを基盤とするローカルのスクラッチストレージを提供します。これは共有ファイルシステムではなく、複数の書き込み元による同時ライブマウントには対応していません。実行中のサンドボックスが互いのファイルシステムを読み書きすることはありません。サンドボックス間で状態を共有するには、スナップショットの作成とリストアを行う必要があります。SDK のサンプル
サンドボックスを起動し、実行中のスナップショットを取得してフォークし、停止時にスナップショットを取得し、スナップショットを管理する、実行可能な完全な Python サンプルについては、cwsandbox-client リポジトリの file_system_snapshots.py を参照してください。TypeScript については、cwsandbox-js リポジトリの file-system-snapshots.ts に、実行中のスナップショットを取得してリストアし、スナップショットを管理するサンプルがあります。
関連リソース
- ファイルシステムスナップショットで Bring your own bucket を使用する: 自身が所有するバケットにスナップショットを保存する方法について説明します。
- Volumes: スクラッチボリュームと、複数のサンドボックスで共有できる登録済み Volume について説明します。
-
サンドボックスのライフサイクル:
stop()の動作とサンドボックスの状態について説明します。 - Python クライアント: SDK のインストール方法と API の詳細について説明します。