创建和管理卷池

注意： 所有 Google Cloud客户都可以使用 Filestore 代理卷功能进行评估和非生产用途。如需为您的Google Cloud 项目申请访问权限，请提交 Filestore 代理卷访问权限申请表单。在有限的正式版计划下，我们根据许可名单提供生产环境支持。如需查看您是否符合条件或申请制作支持，请使用访问权限申请表单。

卷池是顶级区域级资源，用于管理项目和虚拟私有云 (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 和 102400 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：卷池的标识符。

获取有关卷池的信息

如需检索有关特定卷池的详细信息，请执行以下操作：

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 CSI 驱动程序和 GKE 编排会自动管理卷池中的卷预配。如需了解详情，请参阅将 Filestore 代理卷与 GKE 搭配使用。

如果您想通过自己的编排平台使用 Filestore 代理卷，而无需使用 GKE 进行存储，则可以使用 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])?$ 匹配。

创建卷

如需在卷池内预配单个卷，请向 volumes.create 端点发送 HTTP POST 请求：

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"

后续步骤

• 设置 Filestore 代理卷。
• 为 Filestore 代理卷配置 GKE 环境。