Filestore-Agent-Volumes mit der REST API erstellen und verwalten

Hinweis: Filestore-Agent-Volumes sind im Rahmen eines Allowlisted GA (AGA)-Programms verfügbar. Wenn Sie Zugriff für Ihr Google Cloud -Projekt anfordern möchten, reichen Sie das Anfrageformular für den Zugriff auf Filestore-Agent-Volumes ein.

Wenn Sie Filestore-Agent-Volumes mit Ihrer eigenen Orchestrierungsplattform, VM-basierten Sandboxes oder Containerumgebungen verwenden, die nicht auf der Google Kubernetes Engine (GKE) basieren, können Sie einzelne Volumes in einem Volume-Pool direkt über die Filestore REST API bereitstellen und verwalten.

Hinweis: Wenn Sie Arbeitslasten in GKE bereitstellen, müssen Sie Volumes nicht manuell bereitstellen oder verwalten. Der Filestore-CSI-Treiber und die GKE-Orchestrierung verwalten die Volume-Bereitstellung aus Ihrem Volume-Pool automatisch. Weitere Informationen finden Sie unter GKE-Umgebung für Filestore-Agent-Volumes einrichten.

Hinweis

1. Schließen Sie die Ersteinrichtung des Projekts und des Private Service Connect-Netzwerks (PSC) unter Filestore-Agent-Volumes einrichten ab.
2. Regionales Volume-Pool erstellen und verwalten

Volume erstellen

REST API

Wenn Sie ein einzelnes Volume in einem Volume-Pool bereitstellen möchten, senden Sie eine HTTP-POST-Anfrage an den volumes.create-Endpunkt:

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

Ersetzen Sie Folgendes:

• PROJECT_ID: die Projekt-ID von Google Cloud .
• LOCATION: die Region, die den übergeordneten Volume-Pool enthält, z. B. us-central1.
• VOLUME_POOL_ID: die Kennung des übergeordneten Volume-Pools.
• VOLUME_ID: die Kennung für das Volume, die mit ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$ übereinstimmt.

Die Volume-Bereitstellung ist in weniger als ein bis zwei Sekunden abgeschlossen. Die API gibt die Volume-Ressource direkt zurück. Sie können beim Erstellen des Volumes auch ein benutzerdefiniertes Volume-Kontingent (quotaMib) und dynamische NFS-Exportoptionen (ipAcls) angeben:

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

Notieren Sie sich die Werte, die in mountPoint zurückgegeben werden:

• ipAddress: die interne IP-Adresse des NFS-Bereitstellungsendpunkts in Ihrem VPC-Netzwerk.
• mountName: die NFS-Exportpfadkomponente, die bereitgestellt werden soll.

Volume bereitstellen

Nachdem Sie ein Volume bereitgestellt haben, kann Ihr Orchestrator den NFSv3-Export des Volumes direkt auf jeder Client-VM oder jedem Containerhost bereitstellen, die bzw. der mit demselben VPC-Netzwerk verbunden ist:

1. Achten Sie darauf, dass die NFS-Client-Dienstprogramme auf dem Host installiert sind (z. B. nfs-common unter Debian oder Ubuntu).

2. Erstellen Sie ein Bereitstellungsverzeichnis und stellen Sie das Volume mit den ipAddress- und mountName-Werten bereit, die im mountPoint des Volumes zurückgegeben werden:

   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
   

   Ersetzen Sie Folgendes:

   • MOUNT_DIR: der lokale Verzeichnispfad, in dem das Volume bereitgestellt wird, z. B. /workspace.
   • IP_ADDRESS: der mountPoint.ipAddress-Wert, der beim Erstellen oder Abrufen des Volumes zurückgegeben wird.
   • MOUNT_NAME: der mountPoint.mountName-Wert, der beim Erstellen oder Abrufen des Volumes zurückgegeben wird.

Volumes verwalten

REST API

Ersetzen Sie in jeder der folgenden Anfragen Folgendes:

• PROJECT_ID: die Projekt-ID von Google Cloud .
• LOCATION: die Region, die den übergeordneten Volume-Pool enthält.
• VOLUME_POOL_ID: die Kennung des übergeordneten Volume-Pools.
• VOLUME_ID: die Kennung des Volumes.

Volume-Details abrufen

So rufen Sie Details zu einem vorhandenen Volume auf, einschließlich mountPoint und aktuellem Lebenszyklus-state:

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"

Volumes in einem Pool auflisten

So listen Sie alle in einem Volume-Pool bereitgestellten Volumes auf:

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-Kontingent aktualisieren

Wenn Sie das Speicherkontingent für ein aktives Volume erhöhen möchten, senden Sie eine HTTP-PATCH-Anfrage mit der Angabe updateMask=quotaMib. Das Volume-Kontingent kann nur erhöht werden. Das Reduzieren des Volume-Kontingents wird nicht unterstützt:

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"

IP-ACLs für Volumes aktualisieren

Wenn Sie den NFS-Zugriff auf eine bestimmte Sandbox-Client-IP-Adresse beschränken oder IP-Exportregeln aktualisieren möchten, senden Sie eine HTTP-PATCH-Anfrage mit 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"

Volume löschen

Wenn eine KI-Agentensitzung beendet oder eine sitzungsspezifische Sandbox beendet wird, löschen Sie das Volume, um Kontingent im Pool freizugeben:

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"

Arbeitsbereich mit Volume-Snapshot klonen

Wenn Sie bereits einen Volume-Pool im Status READY und ein vorhandenes Quell-Volume im Status HOT haben, können Sie einen Volume-Snapshot erstellen, um den Status eines Agent-Volumes zu einem bestimmten Zeitpunkt zu erfassen. So können Sie Arbeitsbereiche später klonen oder verzweigen.

Hinweis: Volume-Snapshots werden mit der Ressourcensammlung backups und dem Feld sourceVolume verwaltet.

REST API

Volume-Snapshot erstellen

1. Senden Sie eine HTTP-POST-Anfrage an den backups.create-Endpunkt. Geben Sie dabei den vollständigen Ressourcennamen des Volumes im Feld sourceVolume an und ersetzen Sie SNAPSHOT_ID durch eine eindeutige Kennung für den 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. Die Anfrage gibt einen Vorgang mit langer Ausführungszeit zurück. Fragen Sie den Vorgang ab oder rufen Sie die Snapshot-Ressource ab, bis der state-Wert READY ist, bevor Sie Volumes daraus klonen:

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

Volume aus einem Snapshot klonen

Wenn Sie ein Volume aus einem Snapshot klonen möchten, muss der Quell-Snapshot von einem Volume im selben Volume-Pool stammen.

1. Sende eine HTTP-POST-Anfrage an den volumes:createFromSource-Endpunkt. Übergeben Sie ipAcls im Anfragetext, um Exportberechtigungen zu konfigurieren und das geklonte Volume in der HOT-Stufe zu aktivieren:

   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"
   

   Ersetzen Sie Folgendes:

   • SNAPSHOT_ID: die ID des Quell-Snapshots im selben Volume-Pool.
   • CLONED_VOLUME_ID: die ID für das neue geklonte Volume.

2. Die Anfrage gibt einen Vorgang mit langer Ausführungszeit zurück. Fragen Sie den Vorgang ab, bis done den Wert true hat:

   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. Rufen Sie nach Abschluss des Vorgangs volumes.get auf (oder prüfen Sie die Antwort des abgeschlossenen Vorgangs), um die mountPoint (ipAddress und mountName) des neuen Volumes vor dem Bereitstellen abzurufen:

   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"
   

Das Klonen von Volumes aus Snapshots dauert 3 Sekunden pro GB oder 1,5 Sekunden pro 10.000 Dateien.

Volume auf COLD verschieben

REST API

Wenn Sie einen inaktiven Arbeitsbereich in den Cold Storage verschieben möchten, senden Sie eine HTTP-PATCH-Anfrage, um den Volume-Status auf COLD zu aktualisieren und ipAcls zu löschen:

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"

So stellen Sie ein Volume von der COLD-Stufe auf der HOT-Stufe wieder her, wenn eine Agent-Sitzung fortgesetzt wird:

1. Rufen Sie die benutzerdefinierte Methode unfreeze auf und übergeben Sie ipAcls im Anfragetext, um den Clientzugriff zu konfigurieren und den Bereitstellungspunkt des Volumes in der HOT-Stufe zu aktivieren:

   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. Die Anfrage gibt einen Vorgang mit langer Ausführungszeit zurück. Fragen Sie den Vorgang ab, bis done den Wert true hat:

   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. Wenn ein Volume aus der COLD-Stufe wiederhergestellt wird, weist Filestore einen neuen NFS-Bereitstellungsendpunkt aus dem Volume-Pool zu, sodass sich mountPoint.ipAddress und mountPoint.mountName ändern. Rufen Sie die aktualisierte mountPoint aus der Antwort des abgeschlossenen Vorgangs oder durch Aufrufen von volumes.get ab, bevor Sie das Volume neu bereitstellen:

   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"
   

Nächste Schritte

• Volume-Pools verwalten und überwachen.
• GKE-Umgebung für Filestore-Agent-Volumes konfigurieren