ファイルシステムスナップショット

auth を省略している例では、CWSANDBOX_API_KEY に設定された CoreWeave API アクセストークンを使用します。Forge APIキーで認証する場合は、はじめにの手順に従い、取得した AuthHeaders を操作に渡してください。HTTP API の例では、FORGE_API_KEY に設定された Forge APIキーを使用します。代わりに CoreWeave API アクセストークンを使用する場合は、CWSANDBOX_API_KEY にそのトークンを設定し、各リクエストの -H "x-wandb-api-key: $FORGE_API_KEY" を -H "Authorization: Bearer $CWSANDBOX_API_KEY" に置き換えてください。認証情報には、サンドボックスとそのスナップショットを所有するアカウントのものを使用してください。

ファイルシステムスナップショット (FSS) を使用すると、サンドボックスでローカルの作業ディレクトリに書き込み、そのディレクトリを不変のスナップショットとしてオブジェクトストレージに取得し、後で新しいサンドボックスにリストアできます。FSS を使用して、run 間でサンドボックスのファイルシステムを一時停止・再開したり、1 つのスナップショットから複数のサンドボックスにフォークし、それぞれを独立して変更したりできます。

仕組み

FSS を使用したサンドボックスは、選択したパスに書き込み可能なスクラッチファイルシステムをマウントします。ランナーはこのマウントを直接のオブジェクトストレージマウントではなく EmptyDir でバックアップします。スナップショットとリストアの操作では、そのローカルファイルシステムと組織スコープのオブジェクトストレージバケットの間で tarball をコピーします。各スナップショットは、サーバーによって割り当てられた fileSystemSnapshotId で識別される FileSystemSnapshot リソースです。スナップショットには 3 つの特性があります。

不変: スナップショットを作成すると 1 つのアーカイブが書き込まれます。スナップショットをリストアしてもソースのスナップショットは変更されないため、後でリストアしても常に元のバイトが表示されます。
組織スコープ: ご自身の組織で作成されたスナップショットのみをリストアできます。他の組織のスナップショット ID は見つからないものとして扱われます。
独立したライフサイクル: スナップショットはサンドボックスとは別に管理されます。サンドボックスを削除してもそのスナップショットは削除されず、スナップショットを削除してもそれから実行中のサンドボックスには影響しません。

デフォルトでは、CoreWeave がスナップショットを保持するオブジェクトストレージバケットをプロビジョニングおよび管理します。代わりにご自身で所有および管理するバケットにスナップショットを保存する場合は、CoreWeave アカウントとバケットの前提条件について Bring your own bucket を使用するを参照してください。

スナップショットマウントでサンドボックスを起動する

サンドボックスは、2 つのファイルシステムソースのいずれかから起動できます。新しく空のスクラッチファイルシステム、または既存のスナップショットのリストアです。

新規スクラッチ

新規スクラッチのファイルシステムは空の状態で開始され、後からスナップショットを作成できます。run の実行中に書き込み可能なローカル状態が必要なワークフローで使用してください。

Python
HTTP API

from cwsandbox import Sandbox, FileSystemSnapshotOptions

with Sandbox.run(
    container_image="ubuntu:22.04",
    file_system_snapshot=FileSystemSnapshotOptions(mount_path="/work", size="10Gi"),
) as sandbox:
    sandbox.exec(["sh", "-c", "echo hello > /work/data.txt"]).result()

fileSystem.mountPath と fileSystem.size を設定します。空の状態で開始する場合は、fileSystemSnapshot を設定しないでください。

curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes \
  -H "x-wandb-api-key: $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "containerImage": "ubuntu:22.04",
    "command": "sleep",
    "args": ["3600"],
    "fileSystem": {
      "mountPath": "/work",
      "size": "10Gi"
    }
  }'

スナップショットからリストアする

リストアでは、既存のスナップショットからファイルシステムを起動します。マウントのスナップショットソースにスナップショット ID を設定します。

Python
HTTP API

from cwsandbox import Sandbox, FileSystemSnapshotOptions

with Sandbox.run(
    container_image="ubuntu:22.04",
    file_system_snapshot=FileSystemSnapshotOptions(
        mount_path="/work",
        file_system_snapshot_id="fss_...",
    ),
) as sandbox:
    contents = sandbox.exec(["cat", "/work/data.txt"]).result()
    print(contents.stdout)

curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes \
  -H "x-wandb-api-key: $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "containerImage": "ubuntu:22.04",
    "command": "sleep",
    "args": ["3600"],
    "fileSystem": {
      "mountPath": "/work",
      "size": "10Gi",
      "fileSystemSnapshot": {
        "fileSystemSnapshotId": "fss_..."
      }
    }
  }'

スナップショットをリストアするには、ステータスが READY である必要があります。まだ CREATING のスナップショットをリストアすると失敗します。スナップショットのステータスと失敗を参照してください。

スナップショットを撮る

サンドボックスを停止したとき (on stop) と、実行中のサンドボックスから (mid-life) の2つの方法でスナップショットを取得することができます。

停止時のスナップショット

シャットダウン時にサンドボックスのファイルシステムを保持するには、停止時のスナップショットを有効にしてサンドボックスを停止します。一時停止と再開は、このパターンで実現します。スナップショットを取得してサンドボックスを停止し、後でそのスナップショットをリストアする新しいサンドボックスを起動します。

Python
HTTP API

sandbox.stop(snapshot_on_stop=True).result()
print(sandbox.file_system_snapshot_id)

StopSandbox は、スナップショットのリクエストが受け付けられると fileSystemSnapshotId を返します。waitForReady を true に設定すると、呼び出しは maxTimeoutSeconds を上限として、スナップショットが READY または FAILED になるまで待機します。設定しない場合は、スナップショットがまだ CREATING の状態でも呼び出しが返ることがあります。[SANDBOX-ID] は、停止するサンドボックスの ID に置き換えてください。

curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes/[SANDBOX-ID]/stop \
  -H "x-wandb-api-key: $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sandboxId": "[SANDBOX-ID]",
    "fileSystemSnapshotOnStop": true,
    "waitForReady": true,
    "idempotencyKey": "stop-[SANDBOX-ID]-snapshot-1",
    "maxTimeoutSeconds": 600
  }'

実行中のスナップショット

実行中のスナップショットは、サンドボックスを停止せずにその状態を取得します。サンドボックスはその後も実行を継続します。

Python
HTTP API

snapshot() はデフォルトでスナップショットが READY になるまで待機し、スナップショット ID を返します。

snapshot_id = sandbox.snapshot().result()
print(f"Created snapshot {snapshot_id}")

CreateFileSystemSnapshot は、停止時のスナップショットと同じ制御パラメーター idempotencyKey、waitForReady、maxTimeoutSeconds を受け入れます。StopSandbox とは異なり、waitForReady のデフォルトは true です。[SANDBOX-ID] を、スナップショットを作成する実行中のサンドボックスの ID に置き換えてください。

curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes/[SANDBOX-ID]/file-system-snapshots \
  -H "x-wandb-api-key: $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sandboxId": "[SANDBOX-ID]",
    "waitForReady": true,
    "maxTimeoutSeconds": 600
  }'

waitForReady を false に設定した場合、成功時の応答は、スナップショットの行が作成され、スナップショットコマンドが送信されたことを意味します。アーカイブはまだ CREATING の状態である可能性があり、その後 FAILED になることもあります。リストアする前に、スナップショットの状態をポーリングして確認してください。

スナップショットをフォークする

同じスナップショットを複数のサンドボックスにリストアできます。各スナップショットは不変であるため、リストアされたサンドボックスは同一のバイト列から開始し、書き込みに伴ってそれぞれ異なる状態になります。

停止時のスナップショット、または実行中のスナップショットを使用して、READY 状態のスナップショットを作成します。
fileSystemSnapshotId にそのスナップショットを設定して、サンドボックス A を起動します。
同じ fileSystemSnapshotId を使用して、サンドボックス B を起動します。
サンドボックス A とサンドボックス B への書き込みは、それぞれ独立して状態を変化させます。ソースのスナップショットは変更されないため、後から同じ ID を使用してリストアしても、どちらのフォークへの書き込みも反映されず、元のスナップショットが使用されます。

from cwsandbox import Sandbox, FileSystemSnapshotOptions

# 同じスナップショットを、互いに独立した 2 つのサンドボックスにリストアします。
with Sandbox.run(
    file_system_snapshot=FileSystemSnapshotOptions(mount_path="/work", file_system_snapshot_id=snapshot_id),
) as fork_a, Sandbox.run(
    file_system_snapshot=FileSystemSnapshotOptions(mount_path="/work", file_system_snapshot_id=snapshot_id),
) as fork_b:
    fork_a.exec(["sh", "-c", "echo a >> /work/data.txt"]).result()
    fork_b.exec(["sh", "-c", "echo b >> /work/data.txt"]).result()

スナップショットを管理する

スナップショットは、作成元のサンドボックスとは独立して一覧表示、取得、削除できます。

Python
HTTP API

from cwsandbox import Sandbox

# 組織内のすべてのスナップショットを一覧表示します。
snapshots = Sandbox.list_snapshots().result()

# 1 つのスナップショットの詳細を取得します。
snapshot = Sandbox.get_snapshot(snapshot_id).result()
print(f"{snapshot.file_system_snapshot_id}: {snapshot.size_bytes} bytes")

# スナップショットを削除します。missing_ok を指定すると呼び出しがべき等になります。
Sandbox.delete_snapshot(snapshot_id, missing_ok=True).result()

[SNAPSHOT-ID] を、取得または削除するスナップショットの ID に置き換えてください。

# 組織スコープのスナップショットを一覧表示します。
curl https://api.cwsandbox.com/v1beta2/file-system-snapshots \
  -H "x-wandb-api-key: $FORGE_API_KEY"

# 1 つのスナップショットを取得します。
curl https://api.cwsandbox.com/v1beta2/file-system-snapshots/[SNAPSHOT-ID] \
  -H "x-wandb-api-key: $FORGE_API_KEY"

# 1 つのスナップショットを削除します。
curl -X DELETE https://api.cwsandbox.com/v1beta2/file-system-snapshots/[SNAPSHOT-ID] \
  -H "x-wandb-api-key: $FORGE_API_KEY"

list_snapshots()、get_snapshot()、delete_snapshot() では、auth 引数で AuthHeaders オブジェクトを渡すこともできます。

スナップショットのステータスと失敗

スナップショットは非同期で作成されます。スナップショットリクエストが成功して fileSystemSnapshotId が返された時点でも、アーカイブの書き込みがまだ続いていることがあり、その後にスナップショットが失敗する場合があります。これは主に、waitForReady が false の場合や、ランナーのアーカイブ処理中にクライアント側でタイムアウトが発生した場合に起こります。進捗を確認するには、スナップショットを取得して次の 2 つのフィールドを確認します。

status: ライフサイクル状態。終了状態の値は READY と FAILED です。HTTP API は FILE_SYSTEM_SNAPSHOT_STATUS_READY のような完全修飾形式を返します。
statusReason: status が FAILED の場合に設定され、失敗の理由を示します。

スナップショットをリストアする前に、GetFileSystemSnapshot をポーリングして、スナップショットが READY になるまで待機してください。Python クライアントの snapshot() と get_snapshot() では、結果を待機する場合にこのポーリングが自動で行われます。次の表は、主な失敗理由とそれぞれの対処法を示しています。

理由	意味	対処法
`CWSANDBOX_FSS_BUCKET_PROVISIONING`	デフォルトのスナップショットバケットがまだプロビジョニング中です。	しばらくしてから再試行してください。エラーが解消しない場合は、サポートに問い合わせてください。
`CWSANDBOX_FSS_AUTH_FAILED`	認証情報の交換またはバケットの認可に失敗しました。	バケットまたは WIF ポリシーを修正してから再試行してください。CoreWeave が管理するバケットの場合は、サポートに問い合わせてください。
`CWSANDBOX_FSS_TRANSPORT_FAILED`	ランナーがオブジェクトストレージに接続できなかったか、アーカイブの転送に失敗しました。	再試行してください。繰り返し発生する場合は、スナップショット ID を添えてサポートに問い合わせてください。
`CWSANDBOX_FSS_BACKEND_THROTTLED`	オブジェクトストレージでスロットリングまたはバックエンドエラーが継続的に発生しました。	時間をおいて再試行してください。
`CWSANDBOX_FSS_CREATE_TIMED_OUT`	設定されたタイムアウト内にスナップショットが完了しませんでした。	`maxTimeoutSeconds` を大きくして再試行するか、データサイズを減らしてください。
`CWSANDBOX_FSS_CANCELED`	スナップショットがキャンセルされました。通常は、処理中にサンドボックスが強制削除されたことが原因です。	データがまだ必要な場合は、スナップショットの作成を再試行してください。
`CWSANDBOX_FSS_QUOTA_EXCEEDED`	組織がスナップショット数またはストレージの上限に達しました。	不要なスナップショットを削除するか、クォータの引き上げをリクエストしてください。
`CWSANDBOX_FSS_NOT_READY`	リストアで参照されたスナップショットが `READY` ではありません。	スナップショットが `READY` になるまでポーリングするか、別のスナップショットを選択してください。
`CWSANDBOX_FSS_NOT_FOUND`	指定したスナップショットが組織内に存在しません。	スナップショット ID と組織を確認してください。
`CWSANDBOX_FSS_SIZE_EXCEEDED`	リクエストされたファイルシステムのサイズが、サポートされるスクラッチサイズを超えています。	より小さいファイルシステムをリクエストするか、制限についてサポートに問い合わせてください。

ランナーがアーカイブのアップロードを完了したものの結果を記録できなかった場合、バケット内にオブジェクトが存在していても、スナップショットの行が FAILED になることがあります。この場合は、スナップショットの作成を再試行してください。非同期で失敗した場合、プラットフォームは sandbox.file_system_snapshot.async_fail イベントも発行します。これにより、下流の通知システムは、元の呼び出しが返った後に失敗したスナップショットに対応できます。

制限事項

FSS バージョン 1 は、スナップショットを基盤とするローカルのスクラッチストレージを提供します。これは共有ファイルシステムではなく、複数の書き込み元による同時ライブマウントには対応していません。実行中のサンドボックスが互いのファイルシステムを読み書きすることはありません。サンドボックス間で状態を共有するには、スナップショットの作成とリストアを行う必要があります。

SDK のサンプル

サンドボックスを起動し、実行中のスナップショットを取得してフォークし、停止時にスナップショットを取得し、スナップショットを管理する、実行可能な完全な Python サンプルについては、cwsandbox-client リポジトリの file_system_snapshots.py を参照してください。

ファイルシステムスナップショットで Bring your own bucket を使用する: 自身が所有するバケットにスナップショットを保存する方法について説明します。
Volumes: スクラッチボリュームと、複数のサンドボックスで共有できる登録済み Volume について説明します。
サンドボックスのライフサイクル: stop() の動作とサンドボックスの状態について説明します。
Python クライアント: SDK のインストール方法と API の詳細について説明します。

サンドボックス

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

サンドボックスの管理

リファレンス

ファイルシステムスナップショット

仕組み

スナップショットマウントでサンドボックスを起動する

新規スクラッチ

スナップショットからリストアする

スナップショットを撮る

停止時のスナップショット

実行中のスナップショット

スナップショットをフォークする

スナップショットを管理する

スナップショットのステータスと失敗

制限事項

SDK のサンプル

​仕組み

​スナップショットマウントでサンドボックスを起動する

​新規スクラッチ

​スナップショットからリストアする

​スナップショットを撮る

​停止時のスナップショット

​実行中のスナップショット

​スナップショットをフォークする

​スナップショットを管理する

​スナップショットのステータスと失敗

​制限事項

​SDK のサンプル

​関連リソース

仕組み

スナップショットマウントでサンドボックスを起動する

新規スクラッチ

スナップショットからリストアする

スナップショットを撮る

停止時のスナップショット

実行中のスナップショット

スナップショットをフォークする

スナップショットを管理する

スナップショットのステータスと失敗

制限事項

SDK のサンプル

関連リソース