建立及管理磁碟區集區

磁碟區集區是頂層區域性資源，可管理專案和虛擬私有雲 (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：磁碟區集區的 ID，與 ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$ 相符。
  • VPC_NETWORK：現有虛擬私有雲網路的名稱。

要求欄位

要求主體包含下列欄位：

欄位 類型 必填 說明
network string 必填 虛擬私有雲網路的資源路徑，格式為 projects/{project}/global/networks/{network}。網路必須具備有效的 PSC 服務連線政策。
defaultVolumeQuotaMib int64 選用 每個磁碟區的預設配額 (以 MiB 為單位)。這個值必須介於 100 MiB 至 102,400 MiB (100 GiB) 之間。預設值為 1024 MiB。
description string 選用 磁碟區集區的易懂說明。
labels map[string, string] 選用 鍵/值組合，可讓您在 Google Cloud中整理及篩選資源。

回應

這個方法會傳回長時間執行的作業 (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：磁碟區集區的 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 管理磁碟區

如要透過自己的協調平台使用 Filestore 代理程式磁碟區，而不使用 GKE 儲存空間，可以直接使用 REST API 佈建及管理個別磁碟區。

REST API

在下列各項要求中，請將：

  • PROJECT_ID： Google Cloud 專案 ID。
  • LOCATION：包含父項磁碟區集區的區域。
  • VOLUME_POOL_ID：父項磁碟區集區的 ID。
  • VOLUME_ID：卷冊的 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"
    }
  }'

磁碟區佈建作業會在不到一秒內完成。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：虛擬私有雲網路中 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"

後續步驟