Crea e gestisci i volumi per agenti Filestore utilizzando l'API REST

Nota: i volumi per agenti Filestore sono disponibili nell'ambito di un programma GA con lista consentita (AGA). Per richiedere l'accesso per il tuo progetto Google Cloud , invia il modulo di richiesta di accesso ai volumi per agenti Filestore.

Se utilizzi i volumi per agenti Filestore con la tua piattaforma di orchestrazione, sandbox basate su VM o ambienti container non Google Kubernetes Engine (GKE), puoi eseguire il provisioning e gestire i singoli volumi all'interno di un pool di volumi direttamente utilizzando l'API REST Filestore.

Nota: se esegui il deployment dei workload su GKE, non devi eseguire il provisioning o la gestione manuale dei volumi. Il driver CSI di Filestore e l'orchestrazione di GKE gestiscono automaticamente il provisioning dei volumi dal pool di volumi. Per saperne di più, consulta Configura l'ambiente GKE per i volumi degli agenti Filestore.

Prima di iniziare

1. Completa la configurazione iniziale del progetto e del networking di Private Service Connect (PSC) in Configura i volumi per agenti Filestore.
2. Crea un pool di volumi a livello di regione in Crea e gestisci i pool di volumi.

Crea un volume

API REST

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

Sostituisci quanto segue:

• PROJECT_ID: l'ID progetto Google Cloud .
• LOCATION: la regione contenente il pool di volumi principale, ad esempio us-central1.
• 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])?$.

Il provisioning del volume viene completato in meno di uno o due secondi. L'API restituisce direttamente la risorsa Volume. Puoi anche specificare una quota di volume personalizzata (quotaMib) e opzioni di esportazione NFS dinamiche (ipAcls) durante la creazione del 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.

Monta un volume

Dopo aver eseguito il provisioning di un volume, l'orchestratore può montare l'esportazione NFSv3 del volume direttamente su qualsiasi VM client o host container connesso alla stessa rete VPC:

1. Assicurati che le utilità client NFS siano installate sull'host (ad esempio, nfs-common su Debian o Ubuntu).

2. Crea una directory di montaggio e monta il volume utilizzando ipAddress e mountName restituiti in mountPoint del 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
   

   Sostituisci quanto segue:

   • MOUNT_DIR: il percorso della directory locale in cui è montato il volume, ad esempio /workspace.
   • IP_ADDRESS: il valore mountPoint.ipAddress restituito durante la creazione o il recupero del volume.
   • MOUNT_NAME: il valore mountPoint.mountName restituito durante la creazione o il recupero del volume.

Gestisci i volumi

API REST

In ciascuna 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.

Visualizza i dettagli del volume

Per visualizzare i dettagli di un volume esistente, inclusi il mountPoint e il ciclo di vita state attuale:

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 di cui è stato eseguito il 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"

Aggiorna quota volume

Per aumentare la quota di spazio di archiviazione per un volume attivo, invia una richiesta HTTP PATCH specificando updateMask=quotaMib. La quota di volume può essere solo aumentata; la riduzione della quota di volume non è supportata:

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"

Aggiorna gli ACL IP del volume

Per limitare l'accesso NFS a un indirizzo IP client sandbox specifico o aggiornare le regole di esportazione IP, invia una richiesta HTTP PATCH specificando 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"

Elimina un volume

Quando una sessione dell'agente si conclude o una sandbox temporanea termina, 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"

Clona la workstation con lo snapshot del volume

Se hai già un pool di volumi in stato READY e un volume di origine esistente in stato HOT, puoi creare uno snapshot del volume per acquisire lo stato point-in-time di un volume per agenti in modo da poter clonare o creare rami degli spazi di lavoro in un secondo momento.

Nota: gli snapshot dei volumi vengono gestiti utilizzando la raccolta di risorse backups con il campo sourceVolume.

API REST

Crea uno snapshot del volume

1. Invia una richiesta HTTP POST all'endpoint backups.create, specificando il nome completo della risorsa del volume nel campo sourceVolume e sostituendo SNAPSHOT_ID con un identificatore univoco per lo snapshot:

   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 richiesta restituisce un'operazione a lunga esecuzione (LRO). Esegui il polling dell'operazione o esegui una query sulla risorsa snapshot finché il suo state non è READY prima di clonare i volumi:

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

Clona un volume da uno snapshot

Per clonare un volume da uno snapshot, lo snapshot di origine deve provenire da un volume nello stesso pool di volumi.

1. Invia una richiesta POST HTTP all'endpoint volumes:createFromSource. Passa ipAcls nel corpo della richiesta per configurare le autorizzazioni di esportazione e attivare il volume clonato nel livello 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"
   

   Sostituisci quanto segue:

   • SNAPSHOT_ID: l'ID dello snapshot di origine nello stesso pool di volumi.
   • CLONED_VOLUME_ID: l'ID del nuovo volume clonato.

2. La richiesta restituisce un'operazione a lunga esecuzione. Esegui il polling dell'operazione finché 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"
   

3. Al termine dell'operazione, chiama volumes.get (o esamina la risposta dell'operazione completata) per recuperare il mountPoint (ipAddress e mountName) del nuovo volume prima di montarlo:

   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"
   

La clonazione dei volumi dagli snapshot viene completata in 3 secondi per GB o 1,5 secondi per 10.000 file.

Sposta un volume in COLD

API REST

Per spostare un'area di lavoro inattiva in un livello di archiviazione cold, invia una richiesta HTTP PATCH aggiornando lo stato del volume a COLD e cancellando 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"

Per ripristinare un volume dal livello COLD al livello HOT quando una sessione dell'agente riprende:

1. Chiama il metodo personalizzato unfreeze, passando ipAcls nel corpo della richiesta per configurare l'accesso client e attivare il punto di montaggio del volume nel livello 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 richiesta restituisce un'operazione a lunga esecuzione. Esegui il polling dell'operazione finché 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"
   

3. Quando un volume viene ripristinato dal livello COLD, Filestore assegna un nuovo endpoint di montaggio NFS dal pool di volumi, quindi mountPoint.ipAddress e mountPoint.mountName cambiano. Recupera il valore mountPoint aggiornato dalla risposta dell'operazione completata o chiamando volumes.get prima di rimontare il 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"
   

Passaggi successivi

• Gestisci e monitora i pool di volumi.
• Configura l'ambiente GKE per i volumi agente di Filestore.