ボリューム

ボリュームとは、サンドボックスが選択したパスにマウントするストレージです。サンドボックスでは 2 種類のボリュームをサポートしています。スクラッチボリューム は単一のサンドボックスに属し、サンドボックスとともに消滅します。登録済み Volume は組織が一度登録するボリュームで、その後任意の数のサンドボックスがマウントできます。このページは、コンテナーファイルシステムの容量を超えて書き込みを行うサンドボックスが必要な開発者、または複数のサンドボックスで同じデータセットを読み取りたい開発者向けです。終了時には、両方の種類のボリュームをアタッチし、登録済み Volume のライフサイクルを管理できるようになります。

ボリュームタイプを選択する

	スクラッチボリューム	登録済み Volume
宣言元	サンドボックス作成時の `ScratchVolumeOptions`	`Volume.create()`、その後サンドボックス作成時の `RegisteredVolumeOptions`
有効期間	サンドボックスの	任意のサンドボックスとは独立
サンドボックス間での共有	いいえ	はい
バッキングストア	ローカルディスクまたはメモリ	クラスター内の既存の PersistentVolumeClaim (PVC)
サンドボックス削除後の存続	ファイルシステムスナップショットのみを通じて	はい

1 つの run 内の作業スペースにはスクラッチボリュームを使用します。サンドボックスを越えて存続するデータや、複数のサンドボックスが同時に読み取るデータ (共有データセットやモデルの重みなど) には登録済み Volume を使用します。

スクラッチボリューム

スクラッチボリュームの例では auth を省略し、CWSANDBOX_API_KEY に設定された CoreWeave API アクセストークンを使用しています。Forge APIキーを使用する場合は、はじめにの手順に従い、生成された AuthHeaders を Sandbox.run() に渡してください。スクラッチボリュームはサンドボックスとともに作成され、サンドボックスとともに破棄されます。volumes リスト内で ScratchVolumeOptions を使用して宣言します。

from cwsandbox import Sandbox, ScratchVolumeOptions

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

ScratchVolumeOptions は以下のフィールドを受け入れます：

Field	説明
`name`	サンドボックス内のボリューム名。マウントとスナップショットはこの名を参照します。必須。
`mount_path`	プライマリコンテナーにマウントする絶対パス。マウントせずにボリュームを宣言する場合は省略します。
`size`	ボリュームサイズ (例: `"10Gi"`) 。プラットフォームのデフォルトを使用する場合は省略します。
`medium`	バッキングストア: `StorageMedium.DISK` (デフォルト) または `StorageMedium.MEMORY`。
`sub_path`	ルートではなくボリューム内の相対パスをマウントします。
`read_only`	ボリュームを読み取り専用でマウントします。デフォルトは `False` です。
`restore_from_snapshot_id`	作成時にファイルシステムスナップショットをボリュームにリストアします。

ストレージ媒体を選択する

StorageMedium.DISK はボリュームをローカルディスクでバックアップします。StorageMedium.MEMORY は tmpfs でバックアップします。これは高速ですが、マウントするコンテナーのメモリリクエストとポリシーのメモリ上限にカウントされます。無制限の RAM バックアップボリュームはノードを枯渇させる可能性があるため、MEMORY ボリュームは size を宣言する必要があります。絶対量として、またはサンドボックスの解決済みメモリリクエストの整数パーセンテージ (例: "50%") として指定できます。パーセンテージ形式は MEMORY の場合のみ有効です。DISK ボリュームは絶対サイズを使用する必要があります。

from cwsandbox import Sandbox, ScratchVolumeOptions, StorageMedium

with Sandbox.run(
    container_image="ubuntu:22.04",
    volumes=[
        ScratchVolumeOptions(
            name="fast-cache",
            mount_path="/cache",
            size="50%",
            medium=StorageMedium.MEMORY,
        )
    ],
) as sandbox:
    sandbox.exec(["sh", "-c", "df -h /cache"]).result()

複数のコンテナーにスクラッチボリュームをマウントする

mount_path は、ボリュームをプライマリコンテナーにマウントするための便利な機能です。マルチコンテナーのサンドボックスでは、mount_path を省略し、代わりに各コンテナーでマウントを宣言してください。これにより、複数のコンテナーが同じボリュームにアクセスできるようになります。

from cwsandbox import Container, Sandbox, ScratchVolumeOptions, VolumeMount

with Sandbox.run(
    volumes=[ScratchVolumeOptions(name="shared", size="5Gi")],
    containers=[
        Container(
            name="app",
            image="ubuntu:22.04",
            primary=True,
            volume_mounts=[VolumeMount(volume="shared", mount_path="/data")],
        ),
        Container(
            name="sidecar",
            image="ubuntu:22.04",
            volume_mounts=[VolumeMount(volume="shared", mount_path="/data", read_only=True)],
        ),
    ],
) as sandbox:
    sandbox.exec(["sh", "-c", "echo shared > /data/note.txt"]).result()

登録済み Volume

以下の例では、CKS クラスター内の PVC と、CWSANDBOX_API_KEY に設定した CoreWeave API アクセストークンを使用します。PVC-backed Volume を登録またはマウントする前に、独自のコンピュートを使用するの手順を完了してください。登録済み Volume は、いずれかのクラスターに既に存在する PersistentVolumeClaim (PVC) を参照します。登録すると、サンドボックスにクラスター自体へのアクセス権を付与せずに、そのクレームをマウントできるようになります。Volume はメタデータ上の参照です。CoreWeave がデータをコピーすることはなく、Volume を削除してもクレームには影響しません。どのマウントも同じクレームを直接参照するため、あるサンドボックスから書き込んだ内容は、それをマウントしている他のすべてのサンドボックスから確認できます。

Volume を登録

Volume.create() は、Volume を VALIDATING 状態で即座に返します。その後、コントロールプレーンがクレームが存在し、使用可能であることを確認します。マウントする前に wait_until_ready() でポーリングしてください。

from cwsandbox import PvcVolumeSource, Volume

volume = Volume.create(
    "team-data",
    pvc=PvcVolumeSource(
        runner_id="[RUNNER-ID]",
        namespace="[NAMESPACE]",
        claim_name="[PVC-NAME]",
    ),
    description="Shared training data",
).result()

volume.wait_until_ready(timeout=120).result()
print(volume.state, volume.capacity, volume.access_modes)

Volume ID はご自身で選択します。組織内で一意である必要があり、作成後は不変です。

ソースと read_only フラグも作成後は不変です。description のみ後で変更できます。

PvcVolumeSource は以下のフィールドを取ります。

フィールド	説明
`runner_id`	クレームを保持するクラスターを持つランナーです。また、Volume をマウントするサンドボックスがスケジュールされる場所を固定します。必須。
`namespace`	クレームの Kubernetes namespace。必須。
`claim_name`	PersistentVolumeClaim の名前。必須。
`sub_path`	クレーム内のオプションパスで、Volume のルートとして扱います。

Volume.create() で read_only=True を設定すると、Volume 自体のプロパティとして読み取り専用になります。この設定は下限であり、デフォルトではありません。書き込み可能な Volume ではマウントを読み取り専用にできますが、読み取り専用の Volume に書き込むマウントはできません。

登録済み Volume をマウントする

ID で RegisteredVolumeOptions を使用して Volume をマウントします。開始時に Volume が READY でない場合、サンドボックスは CWSANDBOX_VOLUME_NOT_READY で失敗します。

from cwsandbox import RegisteredVolumeOptions, Sandbox

with Sandbox.run(
    container_image="ubuntu:22.04",
    volumes=[
        RegisteredVolumeOptions(
            name="data",
            volume_id="team-data",
            mount_path="/data",
            read_only=True,
        )
    ],
) as sandbox:
    listing = sandbox.exec(["ls", "/data"]).result()
    print(listing.stdout)
    print(sandbox.attached_volume_ids)

RegisteredVolumeOptions には name、volume_id、および / 以外の絶対 mount_path が必要です。また、sub_path を受け入れ、登録時に設定された sub_path と組み合わせることができ、read_only も指定できます。サンドボックスは、マウントした Volumes を attached_volume_ids に反映します。

ローカリティと配置

Volume の locality は配置を制約するかどうかを report します:

cluster_local: Volume は 1 つのクラスターに存在するため、それをマウントするサンドボックスはそのクラスターのランナーにスケジュールされます。PVC-backed の Volume は cluster-local です。
global: Volume は任意のクラスターから到達可能で、配置を制約しません。

1 つのサンドボックスで異なるクラスターからの 2 つの cluster-local Volume をマウントすることは不可能であり、開始は CWSANDBOX_VOLUME_PLACEMENT_CONFLICT で失敗します。

登録済み Volume の管理

組織内の Volume を一覧表示、検査、更新、登録解除するには、以下のオペレーションを使用します。

from cwsandbox import Volume, VolumeState

# 組織の Volume をリストし、必要に応じてフィルターを適用します。
volumes = Volume.list(states=[VolumeState.READY]).result()

# 1 つの Volume を取得します。
volume = Volume.get("team-data").result()
print(volume.state, volume.attached_sandbox_count)

# 説明を更新します。これは唯一の変更可能なフィールドです。
volume.update(description="Shared training data, 2026 refresh").result()

# 必要に応じて、バックのクレームを再確認します。
volume.validate().result()

# Volume を登録解除します。バックの PVC は変更されません。
volume.delete(allow_missing=True).result()

Volume.list() は自動的にページネーションを行い、states と runner_ids のフィルターを受け入れます。delete() は allow_missing=True を受け入れ、これによりすでに削除された Volume の削除が成功し、例外を送出する代わりに成功します。非ターミナル状態のサンドボックスがまだマウントしている Volume を削除しようとすると CWSANDBOX_VOLUME_IN_USE で失敗し、Python クライアントはこれを VolumeInUseError として送出します。まず関連付けたサンドボックスを停止してください。

Volume の状態

登録済み Volume は、そのライフサイクルを通じて次の状態に遷移します。

状態	意味
`VALIDATING`	Volume が受け付けられ、コントロールプレーンが基盤となるクレームを確認しています。
`READY`	検証が成功しました。Volume をマウントできます。
`ERROR`	検証が失敗しました。原因は `state_reason` で確認してください。
`DELETING`	Volume の登録解除が進行中で、マウントできなくなっています。

wait_until_ready() は READY になるまで繰り返し確認します。Volume が ERROR または DELETING に達した場合は VolumeError、先にタイムアウトした場合は VolumeWaitTimeoutError が送出されます。

失敗の理由

この表を使用して、サンドボックスとVolumeの操作が返す可能性のある失敗の理由を解釈してください。

理由	意味	対処方法
`CWSANDBOX_VOLUME_NOT_FOUND`	そのIDのVolumeが組織に存在しません。	IDと組織を確認してください。
`CWSANDBOX_VOLUME_NOT_READY`	サンドボックスの開始で参照されたVolumeが`READY`ではありません。	Volumeが`READY`になるまでポーリングし、その後開始を再試行してください。
`CWSANDBOX_VOLUME_IN_USE`	サンドボックスがまだ関連付けられているため、削除がブロックされました。	関連付けられているサンドボックスを停止し、その後Volumeを削除してください。
`CWSANDBOX_VOLUME_BACKEND_NOT_FOUND`	バッキングクレームが存在しないか、読み取り不能です。	クレームが namespace にまだ存在することを確認し、`validate()`を呼び出してください。
`CWSANDBOX_VOLUME_PLACEMENT_CONFLICT`	関連付けられたVolumeが互換性のないランナーを固定しています。	同じクラスター内にあるVolumeをマウントしてください。
`CWSANDBOX_VOLUME_QUOTA_EXCEEDED`	組織がVolumeの上限に達しました。	未使用のVolumeを削除するか、クォータの引き上げをリクエストしてください。

サンドボックスの関連機能の詳細については、以下のリソースを参照してください：

ファイルシステムスナップショット: サンドボックスのファイルシステムを永続化および復元します。
Grant sandboxes access to AI Object Storage: サンドボックス内からバケットの読み書きを行います。
Sandbox configuration: その他のサンドボックス作成オプション
Distributed File Storage: 登録済み Volume が指す PersistentVolumeClaims を作成します。

サンドボックス

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

サンドボックスの管理

リファレンス