> ## Documentation Index > Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt > Use this file to discover all available pages before exploring further. # ボリューム > サンドボックスに書き込み可能なスクラッチ領域を提供するか、複数のサンドボックスで共有する登録済み Volume をマウントします。 ボリュームとは、サンドボックスが選択したパスにマウントするストレージです。サンドボックスでは 2 種類のボリュームをサポートしています。**スクラッチボリューム** は単一のサンドボックスに属し、サンドボックスとともに消滅します。**登録済み Volume** は組織が一度登録するボリュームで、その後任意の数のサンドボックスがマウントできます。 このページは、コンテナーファイルシステムの容量を超えて書き込みを行うサンドボックスが必要な開発者、または複数のサンドボックスで同じデータセットを読み取りたい開発者向けです。終了時には、両方の種類のボリュームをアタッチし、登録済み Volume のライフサイクルを管理できるようになります。

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

| | スクラッチボリューム | 登録済み Volume | | - | - | - | | 宣言元 | サンドボックス作成時の `ScratchVolumeOptions` | `Volume.create()`、その後サンドボックス作成時の `RegisteredVolumeOptions` | | 有効期間 | サンドボックスの | 任意のサンドボックスとは独立 | | サンドボックス間での共有 | いいえ | はい | | バッキングストア | ローカルディスクまたはメモリ | クラスター内の既存の PersistentVolumeClaim (PVC) | | サンドボックス削除後の存続 | [ファイルシステムスナップショット](/ja/products/sandboxes/file-system-snapshots) のみを通じて | はい | 1 つの run 内の作業スペースにはスクラッチボリュームを使用します。サンドボックスを越えて存続するデータや、複数のサンドボックスが同時に読み取るデータ (共有データセットやモデルの重みなど) には登録済み Volume を使用します。

スクラッチボリューム

スクラッチボリュームの例では `auth` を省略し、`CWSANDBOX_API_KEY` に設定された CoreWeave API アクセストークンを使用しています。Forge APIキーを使用する場合は、[はじめに](/ja/products/sandboxes/get-started#forge-api-key)の手順に従い、生成された `AuthHeaders` を `Sandbox.run()` に渡してください。 スクラッチボリュームはサンドボックスとともに作成され、サンドボックスとともに破棄されます。`volumes` リスト内で `ScratchVolumeOptions` を使用して宣言します。 ```python theme={"system"} 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` | 作成時に[ファイルシステムスナップショット](/ja/products/sandboxes/file-system-snapshots)をボリュームにリストアします。 |

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

`StorageMedium.DISK` はボリュームをローカルディスクでバックアップします。`StorageMedium.MEMORY` は tmpfs でバックアップします。これは高速ですが、マウントするコンテナーのメモリリクエストとポリシーのメモリ上限にカウントされます。 無制限の RAM バックアップボリュームはノードを枯渇させる可能性があるため、`MEMORY` ボリュームは `size` を宣言する必要があります。絶対量として、またはサンドボックスの解決済みメモリリクエストの整数パーセンテージ (例: `"50%"`) として指定できます。パーセンテージ形式は `MEMORY` の場合のみ有効です。`DISK` ボリュームは絶対サイズを使用する必要があります。 ```python theme={"system"} 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` を省略し、代わりに各コンテナーでマウントを宣言してください。これにより、複数のコンテナーが同じボリュームにアクセスできるようになります。 ```python theme={"system"} 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 を登録またはマウントする前に、[独自のコンピュートを使用する](/ja/products/sandboxes/get-started-cks)の手順を完了してください。 登録済み Volume は、いずれかのクラスターに既に存在する PersistentVolumeClaim (PVC) を参照します。登録すると、サンドボックスにクラスター自体へのアクセス権を付与せずに、そのクレームをマウントできるようになります。Volume はメタデータ上の参照です。CoreWeave がデータをコピーすることはなく、Volume を削除してもクレームには影響しません。 どのマウントも同じクレームを直接参照するため、あるサンドボックスから書き込んだ内容は、それをマウントしている他のすべてのサンドボックスから確認できます。

Volume を登録

`Volume.create()` は、Volume を `VALIDATING` 状態で即座に返します。その後、コントロールプレーンがクレームが存在し、使用可能であることを確認します。マウントする前に `wait_until_ready()` でポーリングしてください。 ```python theme={"system"} 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` で失敗します。 ```python theme={"system"} 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 を一覧表示、検査、更新、登録解除するには、以下のオペレーションを使用します。 ```python theme={"system"} 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を削除するか、クォータの引き上げをリクエストしてください。 | サンドボックスの関連機能の詳細については、以下のリソースを参照してください： * [ファイルシステムスナップショット](/ja/products/sandboxes/file-system-snapshots): サンドボックスのファイルシステムを永続化および復元します。 * [Grant sandboxes access to AI Object Storage](/ja/products/sandboxes/operations/object-storage-access): サンドボックス内からバケットの読み書きを行います。 * [Sandbox configuration](/ja/products/sandboxes/client/guides/sandbox-configuration): その他のサンドボックス作成オプション * [Distributed File Storage](/products/storage/distributed-file-storage/create-volumes): 登録済み Volume が指す PersistentVolumeClaims を作成します。