Crea y administra grupos de volúmenes

Un grupo de volúmenes es el recurso regional de nivel superior que administra un grupo compartido de capacidad de almacenamiento y operaciones de IOPS para tu proyecto y tu red de nube privada virtual (VPC). Dentro de un grupo de volúmenes, puedes aprovisionar hasta 1 millón de volúmenes independientes y ligeros para zonas de pruebas de agentes de IA, espacios de trabajo de desarrolladores o cargas de trabajo generales de múltiples usuarios.

Antes de comenzar

Completa los requisitos previos que se describen en Configura volúmenes del agente de Filestore.

Crea un grupo de volúmenes

API de REST

Para crear un grupo de volúmenes, envía una solicitud HTTP POST al extremo volumePools.create:

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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la región en la que se implementa el grupo, como us-central1.
  • VOLUME_POOL_ID: Es el identificador del grupo de volúmenes, que coincide con ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$.
  • VPC_NETWORK: Es el nombre de una red de VPC existente.

Campos de solicitud

El cuerpo de la solicitud contiene los siguientes campos:

Campo Tipo Obligatorio Descripción
network string Obligatorio Es la ruta del recurso de tu red de VPC, con el siguiente formato: projects/{project}/global/networks/{network}. La red debe tener una política de conexión de servicio de PSC válida.
defaultVolumeQuotaMib int64 Opcional Es la cuota predeterminada por volumen en MiB. El valor debe estar entre 100 MiB y 102,400 MiB (100 GiB). El valor predeterminado es 1,024 MiB.
description string Opcional Es una descripción fácil de usar del grupo de volumen.
labels map[string, string] Opcional Son pares clave-valor que te permiten organizar y filtrar recursos en Google Cloud.

Respuesta

El método devuelve un objeto de operación de larga duración (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
}

Sondea la operación hasta que done sea 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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la región en la que se implementa el grupo de volúmenes, como us-central1.
  • OPERATION_ID: Es el ID de operación que se devolvió en la respuesta de creación.

Cuando se completa, la operación devuelve el objeto VolumePool con el estado READY.

Administra grupos de volúmenes

Puedes ver detalles sobre los grupos de volúmenes existentes, enumerar los grupos dentro de una región, actualizar configuraciones como etiquetas y cuotas de capacidad, o borrar grupos de volúmenes.

API de REST

En cada una de las siguientes solicitudes, reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la región en la que se implementa el grupo de volúmenes, como us-central1.
  • VOLUME_POOL_ID: Es el identificador del grupo de volúmenes.

Obtén información sobre un grupo de volúmenes

Para recuperar detalles sobre un grupo de volúmenes específico, haz lo siguiente:

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"

Enumera grupos de volúmenes

Para enumerar todos los grupos de volúmenes en una región determinada, haz lo siguiente:

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

Actualiza un grupo de volúmenes

Para actualizar la descripción, las etiquetas o la cuota predeterminada de un grupo de volúmenes existente, envía una solicitud HTTP PATCH con un parámetro de consulta updateMask:

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"
    }
  }'

Borra un grupo de volúmenes

Antes de borrar un grupo de volúmenes, debes borrar todos los volúmenes secundarios aprovisionados en el grupo. Para borrar un grupo de volúmenes, haz lo siguiente:

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"

Administra volúmenes con la API de REST

Si deseas usar volúmenes de agentes de Filestore sin GKE a través de tu propia plataforma de orquestación para el almacenamiento, puedes aprovisionar y administrar volúmenes individuales directamente con la API de REST.

API de REST

En cada una de las siguientes solicitudes, reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la región que contiene el grupo de volúmenes principal.
  • VOLUME_POOL_ID: Es el identificador del grupo de volúmenes principal.
  • VOLUME_ID: Es el identificador del volumen, que coincide con ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$.

Crear un volumen

Para aprovisionar un volumen individual dentro de un grupo de volúmenes, envía una solicitud HTTP POST al extremo 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"
    }
  }'

El aprovisionamiento del volumen se completa en menos de un segundo. La API devuelve el recurso Volume directamente:

{
  "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"
  }
}

Ten en cuenta los valores que se muestran dentro de mountPoint:

  • ipAddress: Es la dirección IP interna del extremo de activación de NFS dentro de tu red de VPC.
  • mountName: Es el componente de la ruta de acceso de exportación de NFS que se activará.

Obtén detalles del volumen

Para ver los detalles de un volumen existente, incluido su mountPoint, haz lo siguiente:

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"

Enumera los volúmenes en un grupo

Para enumerar todos los volúmenes aprovisionados en un grupo de volúmenes, haz lo siguiente:

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"

Borra un volumen

Cuando finaliza una sesión del agente o se cierra un sandbox efímero, borra el volumen para recuperar la cuota dentro del grupo:

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"

¿Qué sigue?