Creare e gestire i pool di volumi

Un pool di volumi è la risorsa di regione di primo livello che gestisce un pool condiviso di capacità di archiviazione e IOPS per il tuo progetto e la rete Virtual Private Cloud (VPC). All'interno di un pool di volumi, puoi eseguire il provisioning di un massimo di 1 milione di volumi indipendenti e leggeri per sandbox di agenti AI, workspace per sviluppatori o carichi di lavoro multi-tenant generali.

Prima di iniziare

Completa i prerequisiti descritti in Configurare i volumi dell'agente Filestore.

Crea un pool di volumi

API REST

Per creare un pool di volumi, invia una richiesta POST HTTP all'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"

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto Google Cloud .
  • LOCATION: la regione in cui viene eseguito il deployment del pool, ad esempio us-central1.
  • VOLUME_POOL_ID: l'identificatore del pool di volumi, corrispondente a ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$.
  • VPC_NETWORK: il nome di una rete VPC esistente.

Campi di richiesta

Il corpo della richiesta contiene i seguenti campi:

Campo Tipo Obbligatorio Descrizione
network string Obbligatorio Il percorso della risorsa della tua rete VPC, nel formato: projects/{project}/global/networks/{network}. La rete deve avere una policy di connessione al servizio PSC valida.
defaultVolumeQuotaMib int64 Facoltativo La quota predefinita per volume in MiB. Il valore deve essere compreso tra 100 MiB e 102400 MiB (100 GiB). Il valore predefinito è 1024 MiB.
description string Facoltativo Una descrizione semplice del pool di volumi.
labels map[string, string] Facoltativo Coppie chiave-valore che ti consentono di organizzare e filtrare le risorse in Google Cloud.

Risposta

Il metodo restituisce un oggetto operazione a lunga esecuzione (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
}

Esegui il sondaggio dell'operazione fino a quando done non è 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"

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto Google Cloud .
  • LOCATION: la regione in cui viene deployato il pool di volumi, ad esempio us-central1.
  • OPERATION_ID: l'ID operazione restituito nella risposta alla creazione.

Al termine, l'operazione restituisce l'oggetto VolumePool con stato READY.

Gestire i pool di volumi

Puoi visualizzare i dettagli sui pool di volumi esistenti, elencare i pool all'interno di una regione, aggiornare le configurazioni come le etichette e le quote di capacità o eliminare i pool di volumi.

API REST

In ognuna delle seguenti richieste, sostituisci:

  • PROJECT_ID: l'ID progetto Google Cloud .
  • LOCATION: la regione in cui viene deployato il pool di volumi, ad esempio us-central1.
  • VOLUME_POOL_ID: l'identificatore del pool di volumi.

Ottenere informazioni su un pool di volumi

Per recuperare i dettagli di un pool di volumi specifico:

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"

Elenca i pool di volumi

Per elencare tutti i pool di volumi in una determinata regione:

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

Aggiorna un pool di volumi

Per aggiornare la descrizione, le etichette o la quota predefinita di un pool di volumi esistente, invia una richiesta HTTP PATCH con un parametro di query 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"
    }
  }'

Elimina un pool di volumi

Prima di eliminare un pool di volumi, devi eliminare tutti i volumi secondari di cui è stato eseguito il provisioning all'interno del pool. Per eliminare un pool di volumi:

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"

Gestire i volumi utilizzando l'API REST

Se vuoi utilizzare i volumi dell'agente Filestore senza GKE tramite la tua piattaforma di orchestrazione per l'archiviazione, puoi eseguire il provisioning e gestire i singoli volumi direttamente utilizzando l'API REST.

API REST

In ognuna delle seguenti richieste, sostituisci:

  • PROJECT_ID: l'ID progetto Google Cloud .
  • LOCATION: la regione contenente il pool di volumi principale.
  • VOLUME_POOL_ID: l'identificatore del pool di volumi principale.
  • VOLUME_ID: l'identificatore del volume, corrispondente a ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$.

Crea un volume

Per eseguire il provisioning di un singolo volume all'interno di un pool di volumi, invia una richiesta POST HTTP all'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"
    }
  }'

Il provisioning del volume viene completato in meno di un secondo. L'API restituisce direttamente la risorsa 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"
  }
}

Prendi nota dei valori restituiti all'interno di mountPoint:

  • ipAddress: l'indirizzo IP interno dell'endpoint di montaggio NFS all'interno della tua rete VPC.
  • mountName: il componente del percorso di esportazione NFS da montare.

Visualizzare i dettagli del volume

Per visualizzare i dettagli di un volume esistente, incluso il relativo 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"

Elenca i volumi in un pool

Per elencare tutti i volumi sottoposti a provisioning in un pool di volumi:

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"

Eliminare un volume

Quando una sessione dell'agente termina o una sandbox effimera viene chiusa, elimina il volume per recuperare la quota all'interno del 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"

Passaggi successivi