ボリューム プールを作成して管理する

ボリューム プールは、プロジェクトと Virtual Private Cloud（VPC）ネットワークのストレージ容量と IOPS の共有プールを管理する最上位のリージョン リソースです。ボリューム プール内では、AI エージェントのサンドボックス、デベロッパー ワークスペース、一般的なマルチテナント ワークロード用に、最大 100 万個の独立した軽量ボリュームをプロビジョニングできます。

始める前に

Filestore エージェント ボリュームを設定するで説明されている前提条件を満たします。

ボリューム プールを作成する

REST API

ボリューム プールを作成するには、volumePools.create エンドポイントに HTTP POST リクエストを送信します。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "description": "Production volume pool for AI agent sandboxes",
    "network": "projects/PROJECT_ID/global/networks/VPC_NETWORK",
    "defaultVolumeQuotaMib": 2048,
    "labels": {
      "env": "production",
      "workload": "ai-sandboxes"
    }
  }' \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools?volumePoolId=VOLUME_POOL_ID"

次のように置き換えます。

  • PROJECT_ID: Google Cloud プロジェクト ID。
  • LOCATION: プールがデプロイされるリージョン（us-central1 など）。
  • VOLUME_POOL_ID: ボリューム プールの識別子（^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$ と一致）。
  • VPC_NETWORK: 既存の VPC ネットワークの名前。

リクエスト フィールド

リクエスト本文には次のフィールドが含まれます。

フィールド タイプ 必須 説明
network string 必須 VPC ネットワークのリソースパス。形式は projects/{project}/global/networks/{network} です。ネットワークに有効な PSC サービス接続ポリシーが必要です。
defaultVolumeQuotaMib int64 省略可 ボリュームあたりのデフォルトの割り当て（MiB）。値は 100 MiB ～ 102,400 MiB（100 GiB）の範囲で指定する必要があります。デフォルト値は 1,024 MiB です。
description string 省略可 ボリューム プールのわかりやすい説明。
labels map[string, string] 省略可 Google Cloudでリソースを整理してフィルタできる Key-Value ペア。

レスポンス

このメソッドは、長時間実行オペレーション（LRO）オブジェクトを返します。

{
  "name": "projects/my-project/locations/us-central1/operations/operation-1694000000000-abcde",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.filestore.v1beta1.OperationMetadata",
    "createTime": "2026-09-08T10:00:00.000Z",
    "target": "projects/my-project/locations/us-central1/volumePools/my-volume-pool",
    "verb": "create"
  },
  "done": false
}

done が true になるまでオペレーションをポーリングします。

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"

次のように置き換えます。

  • PROJECT_ID: Google Cloud プロジェクト ID。
  • LOCATION: ボリューム プールがデプロイされているリージョン（us-central1 など）。
  • OPERATION_ID: 作成レスポンスで返されたオペレーション ID。

完了すると、オペレーションは状態 READY の VolumePool オブジェクトを返します。

ボリューム プールを管理する

既存のボリュームプールの詳細を表示したり、リージョン内のプールを一覧表示したり、ラベルや容量割り当てなどの構成を更新したり、ボリュームプールを削除したりできます。

REST API

次の各リクエストで、次のように置き換えます。

  • PROJECT_ID: Google Cloud プロジェクト ID。
  • LOCATION: ボリューム プールがデプロイされているリージョン（us-central1 など）。
  • VOLUME_POOL_ID: ボリューム プールの識別子。

ボリューム プールに関する情報を取得する

特定のボリューム プールの詳細を取得するには:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID"

ボリューム プールの一覧を取得する

特定のリージョン内のすべてのボリューム プールを一覧表示するには:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools"

ボリューム プールを更新する

既存のボリューム プールの説明、ラベル、デフォルトの割り当てを更新するには、updateMask クエリ パラメータを含む HTTP PATCH リクエストを送信します。

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID?updateMask=description,labels" \
  -d '{
    "description": "Updated pool description",
    "labels": {
      "env": "production",
      "owner": "platform-team"
    }
  }'

ボリューム プールを削除する

ボリューム プールを削除する前に、プール内にプロビジョニングされたすべての子ボリュームを削除する必要があります。ボリューム プールを削除するには:

curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID"

REST API を使用してボリュームを管理する

独自のオーケストレーション プラットフォームを介して GKE なしで Filestore エージェント ボリュームを使用する場合は、REST API を使用して個々のボリュームを直接プロビジョニングして管理できます。

REST API

次の各リクエストで、次のように置き換えます。

  • PROJECT_ID: Google Cloud プロジェクト ID。
  • LOCATION: 親ボリューム プールを含むリージョン。
  • VOLUME_POOL_ID: 親ボリューム プールの識別子。
  • VOLUME_ID: ボリュームの識別子。^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$ と一致します。

ボリュームを作成

ボリューム プール内の個々のボリュームをプロビジョニングするには、HTTP POST リクエストを volumes.create エンドポイントに送信します。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes?volumeId=VOLUME_ID" \
  -d '{
    "description": "Dynamic tool scratchpad for Agent Worker 12",
    "labels": {
      "agent_id": "worker-12",
      "workflow": "code_eval"
    }
  }'

ボリュームのプロビジョニングが 1 秒以内に完了します。API は Volume リソースを直接返します。

{
  "name": "projects/my-project/locations/us-central1/volumePools/my-volume-pool/volumes/my-volume",
  "description": "Dynamic tool scratchpad for Agent Worker 12",
  "mountPoint": {
    "ipAddress": "10.128.0.45",
    "mountName": "my_volume"
  }
}

mountPoint 内で返された値をメモします。

  • ipAddress: VPC ネットワーク内の NFS マウント エンドポイントの内部 IP アドレス。
  • mountName: マウントする NFS エクスポート パス コンポーネント。

ボリュームの詳細を取得する

mountPoint を含む既存のボリュームの詳細を表示するには:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID"

プール内のボリュームを一覧表示する

ボリューム プールにプロビジョニングされたすべてのボリュームを一覧表示するには:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes"

ボリュームを削除する

エージェント セッションが終了するか、エフェメラル サンドボックスが終了したら、ボリュームを削除してプール内の割り当てを再利用します。

curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID"

次のステップ