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é 20 milhões de volumes independentes e leves (com até 50.000 volumes ativos simultaneamente e até 5 PB de capacidade usada) para Agent Sandboxes de agentes de IA, espaços de trabalho de desenvolvedores ou cargas de trabalho multilocatárias 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,
    "activeVolumeIops": 1000,
    "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 está 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 int32 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 é 1.024 MiB.
activeVolumeIops int32 Opcional Especifica o número de IOPS provisionadas por volume ativo no pool de volumes. O padrão é 3.000 IOPS, e o máximo é 10.000 IOPS. As IOPS são provisionadas e faturadas no nível do pool de volumes. Para mais informações sobre preços, consulte a página de preços do Filestore.
description string Opcional Uma descrição fácil de usar do pool de volumes.
labels map[string, string] Opcional Pares de chave-valor que permitem organizar e filtrar recursos no Google Cloud.
autoFreezeDelay string Opcional O tempo que um volume precisa permanecer desanexado (com ACLs de IP vazias) antes de ser automaticamente transferido para o armazenamento COLD. O formato é uma string de duração que termina com s (por exemplo, 604800s para 7 dias). O padrão é 7 dias.

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
}

Sonde 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.

Depois que o pool de volumes atingir o estado READY, escolha como você quer provisionar e montar volumes do pool:

Gerenciar pools de volumes

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

Console do Google Cloud

É possível visualizar pools de volumes e monitorar a capacidade deles diretamente no console doGoogle Cloud :

  1. No console do Google Cloud , acesse a página Pools de volumes do Filestore.

    Acessar pools de volumes

  2. Clique em qualquer pool de volumes na lista para abrir a página Detalhes do pool de volumes.

  3. Na guia Monitoramento, confira gráficos em tempo real da contagem de volumes ativos, da capacidade de armazenamento, das IOPS e da latência de E/S.

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 ou os rótulos de um pool de volumes, envie uma solicitação 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"
    }
  }'

O método PATCH retorna uma operação de longa duração. É possível pesquisar a operação até que ela seja concluída.

Excluir um pool de volumes

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

Monitorar pools de volumes

É possível monitorar o desempenho, a capacidade e as contagens de volume dos pools de volumes usando o Cloud Monitoring e o console do Google Cloud .

Como monitorar métricas

O Filestore exporta 12 métricas dedicadas no namespace file.googleapis.com/volume_pool/:

Tipo de métrica Nome de exibição Tipo Unidade Descrição
volume_pool/volumes Volumes GAUGE {volume} Número de volumes no pool de volumes, detalhado por estado do ciclo de vida.
volume_pool/used_bytes Bytes usados GAUGE By Capacidade total usada no pool de volumes.
volume_pool/cold_used_bytes Bytes usados do Cold GAUGE By Armazenamento total consumido por volumes no nível COLD dentro do pool de volumes.
volume_pool/provisioned_iops IOPS provisionadas GAUGE {operation}/s Limite de IOPS provisionadas para o pool de volumes.
volume_pool/read_ops_count Contagem de operações de leitura DELTA {operation} Contagem de operações de leitura em todos os volumes do pool.
volume_pool/write_ops_count Contagem de operações de gravação DELTA {operation} Contagem de operações de gravação em todos os volumes no pool de volumes.
volume_pool/total_ops_count Contagem total de operações DELTA {operation} Contagem de operações de leitura e gravação em todos os volumes do pool de volumes.
volume_pool/read_bytes_count Bytes lidos DELTA By Bytes lidos em todos os volumes no pool de volumes.
volume_pool/write_bytes_count Bytes gravados DELTA By Bytes gravados em todos os volumes no pool de volumes.
volume_pool/average_read_latency Latência média de leitura GAUGE ms Latência média das operações de leitura em todos os volumes do pool.
volume_pool/average_write_latency Latência média de gravação GAUGE ms Latência média das operações de gravação em todos os volumes do pool.
volume_pool/metadata_ops_count Contagem de operações de metadados DELTA {operation} Contagem de operações de metadados NFS em todos os volumes no pool de volumes.

A seguir