Créer et gérer des pools de volumes

Un pool de volumes est la ressource régionale de premier niveau qui gère un pool partagé de capacité de stockage et d'IOPS pour votre projet et votre réseau de cloud privé virtuel (VPC). Dans un pool de volumes, vous pouvez provisionner jusqu'à un million de volumes indépendants et légers pour les bacs à sable des agents d'IA, les espaces de travail des développeurs ou les charges de travail multitenants générales.

Avant de commencer

Remplissez les conditions préalables décrites dans Configurer les volumes de l'agent Filestore.

Créer un pool de volumes

API REST

Pour créer un pool de volumes, envoyez une requête HTTP POST au point de terminaison 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"

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet Google Cloud .
  • LOCATION : région dans laquelle le pool est déployé, par exemple us-central1.
  • VOLUME_POOL_ID : identifiant du pool de volumes, correspondant à ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$.
  • VPC_NETWORK : nom d'un réseau VPC existant.

Champs des demandes

Le corps de la requête contient les champs suivants :

Champ Type Obligatoire Description
network string Obligatoire Chemin d'accès à la ressource de votre réseau VPC, au format projects/{project}/global/networks/{network}. Le réseau doit disposer d'une règle de connexion PSC valide.
defaultVolumeQuotaMib int64 Facultatif Quota par défaut par volume en Mio. La valeur doit être comprise entre 100 Mio et 102 400 Mio (100 Gio). La valeur par défaut est de 1 024 Mio.
description string Facultatif Description conviviale du pool de volume.
labels map[string, string] Facultatif Paires clé/valeur qui vous permettent d'organiser et de filtrer les ressources dans Google Cloud.

Réponse

La méthode renvoie un objet d'opération de longue durée (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
}

Interrogez l'opération jusqu'à ce que done soit 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"

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet Google Cloud .
  • LOCATION : région dans laquelle le pool de volumes est déployé, par exemple us-central1.
  • OPERATION_ID : ID d'opération renvoyé dans la réponse de création.

Une fois l'opération terminée, l'objet VolumePool est renvoyé avec l'état READY.

Gérer les pools de volumes

Vous pouvez afficher des informations sur les pools de volumes existants, lister les pools d'une région, mettre à jour des configurations telles que les libellés et les quotas de capacité, ou supprimer des pools de volumes.

API REST

Dans chacune des requêtes suivantes, remplacez :

  • PROJECT_ID : ID du projet Google Cloud .
  • LOCATION : région dans laquelle le pool de volumes est déployé, par exemple us-central1.
  • VOLUME_POOL_ID : identifiant du pool de volumes.

Obtenir des informations sur un pool de volumes

Pour récupérer des informations sur un pool de volumes spécifique :

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"

Lister les pools de volumes

Pour lister tous les pools de volumes d'une région donnée :

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

Mettre à jour un pool de volumes

Pour mettre à jour la description, les libellés ou le quota par défaut d'un pool de volumes existant, envoyez une requête HTTP PATCH avec un paramètre de requête 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"
    }
  }'

Supprimer un pool de volumes

Avant de supprimer un pool de volumes, vous devez supprimer tous les volumes enfants provisionnés dans le pool. Pour supprimer un 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"

Gérer les volumes à l'aide de l'API REST

Si vous souhaitez utiliser des volumes d'agent Filestore sans GKE via votre propre plate-forme d'orchestration pour le stockage, vous pouvez provisionner et gérer des volumes individuels directement à l'aide de l'API REST.

API REST

Dans chacune des requêtes suivantes, remplacez :

  • PROJECT_ID : ID du projet Google Cloud .
  • LOCATION : région contenant le pool de volumes parent.
  • VOLUME_POOL_ID : identifiant du pool de volumes parent.
  • VOLUME_ID : identifiant du volume, correspondant à ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$.

Créer un volume

Pour provisionner un volume individuel dans un pool de volumes, envoyez une requête HTTP POST au point de terminaison 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"
    }
  }'

Le provisionnement du volume s'effectue en moins d'une seconde. L'API renvoie directement la ressource 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"
  }
}

Notez les valeurs renvoyées dans mountPoint :

  • ipAddress : adresse IP interne du point de terminaison d'installation NFS dans votre réseau VPC.
  • mountName : composant du chemin d'exportation NFS à installer.

Obtenir les détails du volume

Pour afficher les détails d'un volume existant, y compris son 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"

Lister les volumes d'un pool

Pour lister tous les volumes provisionnés dans un 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"

Supprimer un volume

Lorsqu'une session d'agent se termine ou qu'un bac à sable éphémère est arrêté, supprimez le volume pour récupérer du quota dans le 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"

Étapes suivantes