Créer et gérer des volumes d'agent Filestore à l'aide de l'API REST

Remarque : Les volumes d'agent Filestore sont disponibles dans le cadre d'un programme de disponibilité générale sur liste d'autorisation (AGA). Pour demander l'accès à votre projet Google Cloud , envoyez le formulaire de demande d'accès aux volumes d'agent Filestore.

Si vous utilisez des volumes d'agent Filestore avec votre propre plate-forme d'orchestration, des bacs à sable basés sur des VM ou des environnements de conteneurs non Google Kubernetes Engine (GKE), vous pouvez provisionner et gérer des volumes individuels dans un pool de volumes directement à l'aide de l'API REST Filestore.

Remarque : Si vous déployez des charges de travail sur GKE, vous n'avez pas besoin de provisionner ni de gérer manuellement les volumes. Le pilote CSI Filestore et l'orchestration GKE gèrent automatiquement le provisionnement des volumes à partir de votre pool de volumes. Pour en savoir plus, consultez Configurer l'environnement GKE pour les volumes d'agent Filestore.

Avant de commencer

1. Effectuez la configuration initiale du projet et de la mise en réseau Private Service Connect (PSC) dans Configurer des volumes d'agent Filestore.
2. Créez un pool de volumes régional dans Créer et gérer des pools de volumes.

Créer un volume

API REST

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

Remplacez les éléments suivants :

• PROJECT_ID : ID de votre projet Google Cloud .
• LOCATION : région contenant le pool de volumes parent, par exemple us-central1.
• 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])?$.

Le provisionnement du volume s'effectue en une à deux secondes. L'API renvoie directement la ressource Volume. Vous pouvez également spécifier un quota de volume personnalisé (quotaMib) et des options d'exportation NFS dynamiques (ipAcls) lors de la création du 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.

Installer un volume

Après avoir provisionné un volume, votre orchestrateur peut installer l'exportation NFSv3 du volume directement sur n'importe quelle VM cliente ou hôte de conteneur connecté au même réseau VPC :

1. Assurez-vous que les utilitaires client NFS sont installés sur l'hôte (par exemple, nfs-common sur Debian ou Ubuntu).

2. Créez un répertoire d'installation et installez le volume à l'aide des valeurs ipAddress et mountName renvoyées dans le mountPoint du volume :

   sudo mkdir -p MOUNT_DIR
   sudo mount -t nfs -o vers=3,proto=tcp,mountproto=tcp,port=2049,mountport=2050 \
       IP_ADDRESS:/MOUNT_NAME MOUNT_DIR
   

   Remplacez les éléments suivants :

   • MOUNT_DIR : chemin d'accès au répertoire local où le volume est installé, par exemple /workspace.
   • IP_ADDRESS : valeur mountPoint.ipAddress renvoyée lors de la création ou de la récupération du volume.
   • MOUNT_NAME : valeur mountPoint.mountName renvoyée lors de la création ou de la récupération du volume.

Gérer les volumes

API REST

Dans chacune des requêtes suivantes, remplacez les éléments suivants :

• PROJECT_ID : ID de votre 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.

Obtenir les détails d'un volume

Pour afficher les détails d'un volume existant, y compris son mountPoint et son state de cycle de vie actuel :

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"

Mettre à jour le quota de volume

Pour augmenter le quota de stockage d'un volume actif, envoyez une requête HTTP PATCH en spécifiant updateMask=quotaMib. Le quota de volume ne peut être qu'augmenté. Il n'est pas possible de le réduire :

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "quotaMib": 4096
  }' \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID?updateMask=quotaMib"

Mettre à jour les LCA d'adresses IP du volume

Pour limiter l'accès NFS à une adresse IP client de bac à sable spécifique ou mettre à jour les règles d'exportation d'adresses IP, envoyez une requête HTTP PATCH en spécifiant updateMask=ipAcls :

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "ipAcls": [
      {
        "ipRanges": ["10.128.0.50/32"],
        "accessMode": "READ_WRITE"
      }
    ]
  }' \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID?updateMask=ipAcls"

Supprimer un volume

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

Cloner l'espace de travail avec un instantané de volume

Si vous disposez déjà d'un pool de volumes à l'état READY et d'un volume source existant à l'état HOT, vous pouvez créer un instantané de volume pour capturer l'état d'un volume d'agent à un moment précis, afin de pouvoir cloner ou créer des branches d'espaces de travail ultérieurement.

Remarque : Les instantanés de volume sont gérés à l'aide de la collection de ressources backups avec le champ sourceVolume.

API REST

Créer un instantané de volume

1. Envoyez une requête HTTP POST au point de terminaison backups.create, en spécifiant le nom complet de la ressource du volume dans le champ sourceVolume et en remplaçant SNAPSHOT_ID par un identifiant unique pour l'instantané :

   curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
       "sourceVolume": "projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID",
       "description": "Baseline workspace snapshot"
     }' \
     "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/backups?backupId=SNAPSHOT_ID"
   

2. La requête renvoie une opération de longue durée (LRO). Interrogez l'opération ou la ressource d'instantané jusqu'à ce que son state soit READY avant de cloner des volumes à partir de celle-ci :

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

Cloner un volume à partir d'un instantané

Pour cloner un volume à partir d'un instantané, l'instantané source doit provenir d'un volume du même pool de volumes.

1. Envoyez une requête HTTP POST au point de terminaison volumes:createFromSource. Transmettez ipAcls dans le corps de la requête pour configurer les autorisations d'exportation et activer le volume cloné dans le niveau HOT :

   curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
       "backup": "projects/PROJECT_ID/locations/LOCATION/backups/SNAPSHOT_ID",
       "volumeId": "CLONED_VOLUME_ID",
       "ipAcls": [
         {
           "ipRanges": ["10.128.0.0/24"],
           "accessMode": "READ_WRITE",
           "squashMode": "NO_ROOT_SQUASH"
         }
       ]
     }' \
     "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes:createFromSource"
   

   Remplacez les éléments suivants :

   • SNAPSHOT_ID : ID de l'instantané source dans le même pool de volumes.
   • CLONED_VOLUME_ID : ID du nouveau volume cloné.

2. La requête renvoie une opération de longue durée. Interrogez l'opération jusqu'à ce que done soit défini sur 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"
   

3. Une fois l'opération terminée, appelez volumes.get (ou inspectez la réponse de l'opération terminée) pour récupérer le mountPoint (ipAddress et mountName) du nouveau volume avant de l'installer :

   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/CLONED_VOLUME_ID"
   

Le clonage de volume à partir d'instantanés s'effectue en trois secondes par Go ou en 1,5 seconde pour 10 000 fichiers.

Définir le niveau d'un volume sur COLD

API REST

Pour transférer un espace de travail inactif vers un stockage à froid, envoyez une requête HTTP PATCH mettant à jour l'état du volume sur COLD et effaçant ipAcls :

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "COLD",
    "ipAcls": []
  }' \
  "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID?updateMask=state,ipAcls"

Pour restaurer un volume du niveau COLD vers le niveau HOT lorsqu'une session d'agent reprend :

1. Appelez la méthode personnalisée unfreeze en transmettant ipAcls dans le corps de la requête pour configurer l'accès client et activer le point d'installation du volume dans le niveau HOT :

   curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
       "ipAcls": [
         {
           "ipRanges": ["10.128.0.0/24"],
           "accessMode": "READ_WRITE",
           "squashMode": "NO_ROOT_SQUASH"
         }
       ]
     }' \
     "https://file.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/volumePools/VOLUME_POOL_ID/volumes/VOLUME_ID:unfreeze"
   

2. La requête renvoie une opération de longue durée. Interrogez l'opération jusqu'à ce que done soit défini sur 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"
   

3. Lorsqu'un volume est restauré à partir du niveau COLD, Filestore attribue un nouveau point de terminaison d'installation NFS à partir du pool de volumes. Par conséquent, mountPoint.ipAddress et mountPoint.mountName changent. Récupérez le mountPoint mis à jour à partir de la réponse de l'opération terminée ou en appelant volumes.get avant de remonter le volume :

   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"
   

Étapes suivantes

• Gérer et surveiller les pools de volumes.
• Configurez l'environnement GKE pour les volumes d'agent Filestore.