Criar e gerenciar pools de volumes

Um pool de volumes é o recurso regional de nível superior que gerencia um pool compartilhado de capacidade de armazenamento e IOPS para seu projeto e rede de nuvem privada virtual (VPC). Em um pool de volumes, é possível provisionar até 1 milhão de volumes independentes e leves para sandboxes de agentes de IA, espaços de trabalho de desenvolvedores ou cargas de trabalho multitenant gerais.

Antes de começar

Conclua os pré-requisitos descritos em Configurar volumes do agente do Filestore.

Criar um pool de volumes

API REST

Para criar um pool de volumes, envie uma solicitação HTTP POST para o endpoint 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"

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: a região em que o pool é implantado, como us-central1.
  • VOLUME_POOL_ID: o identificador do pool de volumes, correspondente a ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$.
  • VPC_NETWORK: o nome de uma rede VPC existente.

Campos de solicitação

O corpo da solicitação contém os seguintes campos:

Campo Tipo Obrigatório Descrição
network string Obrigatório O caminho do recurso da sua rede VPC, no formato: projects/{project}/global/networks/{network}. A rede precisa ter uma política de conexão de serviço do PSC válida.
defaultVolumeQuotaMib int64 Opcional A cota padrão por volume em MiB. O valor precisa estar entre 100 MiB e 102.400 MiB (100 GiB). O valor padrão é 1024 MiB.
description string Opcional Uma descrição fácil de usar do pool de volume.
labels map[string, string] Opcional Pares de chave-valor que permitem organizar e filtrar recursos em Google Cloud.

Resposta

O método retorna um objeto de operação de longa duração (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
}

Pesquise a operação até que done seja 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"

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: a região em que o pool de volumes está implantado, como us-central1.
  • OPERATION_ID: o ID da operação retornado na resposta de criação.

Quando concluída, a operação retorna o objeto VolumePool com o estado READY.

Gerenciar pools de volume

É possível conferir detalhes sobre os pools de volume atuais, listar pools em uma região, atualizar configurações como rótulos e cotas de capacidade ou excluir pools de volume.

API REST

Em cada uma das solicitações a seguir, substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: a região em que o pool de volumes está implantado, como us-central1.
  • VOLUME_POOL_ID: o identificador do pool de volumes.

Receber informações sobre um pool de volumes

Para recuperar detalhes sobre um pool de volumes específico:

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"

Listar pools de volumes

Para listar todos os pools de volumes em uma determinada região:

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

Atualizar um pool de volumes

Para atualizar a descrição, os rótulos ou a cota padrão de um pool de volumes atual, envie uma solicitação HTTP PATCH com um 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"
    }
  }'

Excluir um pool de volumes

Antes de excluir um pool de volumes, é preciso excluir todos os volumes filhos provisionados nele. Para excluir um pool de 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"

Gerenciar volumes usando a API REST

Se você quiser usar volumes de agentes do Filestore sem o GKE na sua própria plataforma de orquestração para armazenamento, provisione e gerencie volumes individuais diretamente usando a API REST.

API REST

Em cada uma das solicitações a seguir, substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: a região que contém o pool de volumes pai.
  • VOLUME_POOL_ID: o identificador do pool de volumes principal.
  • VOLUME_ID: o identificador do volume, correspondente a ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$.

Criar um volume

Para provisionar um volume individual em um pool de volumes, envie uma solicitação HTTP POST ao endpoint 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"
    }
  }'

O provisionamento de volume é concluído em menos de um segundo. A API retorna o recurso Volume diretamente:

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

Observe os valores retornados em mountPoint:

  • ipAddress: o endereço IP interno do endpoint de montagem do NFS na sua rede VPC.
  • mountName: o componente do caminho de exportação do NFS a ser ativado.

Conferir detalhes do volume

Para conferir detalhes de um volume, incluindo o mountPoint dele:

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"

Listar volumes em um pool

Para listar todos os volumes provisionados em um pool de volumes:

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"

Excluir um volume

Quando uma sessão do agente for concluída ou um sandbox efêmero for encerrado, exclua o volume para recuperar a cota no pool:

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"

A seguir