Volume-Pools erstellen und verwalten

Ein Volume-Pool ist die regionale Ressource der obersten Ebene, mit der ein gemeinsam genutzter Pool mit Speicherkapazität und IOPS für Ihr Projekt und Ihr VPC-Netzwerk (Virtual Private Cloud) verwaltet wird. In einem Volume-Pool können Sie bis zu 1 Million unabhängige, schlanke Volumes für KI-Agent-Sandboxes, Entwicklerarbeitsbereiche oder allgemeine Multi-Tenant-Arbeitslasten bereitstellen.

Hinweis

Erfüllen Sie die unter Filestore-Agent-Volumes einrichten beschriebenen Voraussetzungen.

Volume-Pool erstellen

REST API

Wenn Sie einen Volume-Pool erstellen möchten, senden Sie eine HTTP-POST-Anfrage an den volumePools.create-Endpunkt:

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"

Ersetzen Sie Folgendes:

  • PROJECT_ID: die Google Cloud Projekt-ID.
  • LOCATION: Die Region, in der der Pool bereitgestellt wird, z. B. us-central1.
  • VOLUME_POOL_ID: die Kennung für den Volume-Pool, die mit ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$ übereinstimmt.
  • VPC_NETWORK: Der Name eines vorhandenen VPC-Netzwerk.

Anfragefelder

Der Anfragetext enthält die folgenden Felder:

Feld Typ Erforderlich Beschreibung
network string Erforderlich Der Ressourcenpfad Ihres VPC-Netzwerk im Format projects/{project}/global/networks/{network}. Für das Netzwerk muss eine gültige PSC-Richtlinie für Dienstverbindungen vorhanden sein.
defaultVolumeQuotaMib int64 Optional Das Standardkontingent pro Volume in MiB. Der Wert muss zwischen 100 MiB und 102.400 MiB (100 GiB) liegen. Der Standardwert ist 1.024 MiB.
description string Optional Eine benutzerfreundliche Beschreibung des Volumenpools.
labels map[string, string] Optional Schlüssel/Wert-Paare, mit denen Sie Ressourcen in Google Cloudorganisieren und filtern können.

Antwort

Die Methode gibt ein Objekt für einen Vorgang mit langer Ausführungszeit zurück:

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

Fragen Sie den Vorgang ab, bis done gleich true ist:

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

Ersetzen Sie Folgendes:

  • PROJECT_ID: die Google Cloud Projekt-ID.
  • LOCATION: Die Region, in der der Volume-Pool bereitgestellt wird, z. B. us-central1.
  • OPERATION_ID: die Vorgangs-ID, die in der Antwort auf die Erstellung zurückgegeben wird.

Nach Abschluss des Vorgangs wird das VolumePool-Objekt mit dem Status READY zurückgegeben.

Volume-Pools verwalten

Sie können Details zu vorhandenen Volume-Pools aufrufen, Pools in einer Region auflisten, Konfigurationen wie Labels und Kapazitätskontingente aktualisieren oder Volume-Pools löschen.

REST API

Ersetzen Sie in jeder der folgenden Anfragen:

  • PROJECT_ID: die Google Cloud Projekt-ID.
  • LOCATION: Die Region, in der der Volume-Pool bereitgestellt wird, z. B. us-central1.
  • VOLUME_POOL_ID: die Kennung des Volume-Pools.

Informationen zu einem Volume-Pool abrufen

So rufen Sie Details zu einem bestimmten Volume-Pool ab:

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"

Volume-Pools auflisten

So listen Sie alle Volume-Pools in einer bestimmten Region 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 aktualisieren

Wenn Sie die Beschreibung, Labels oder das Standardkontingent eines vorhandenen Volumenpools aktualisieren möchten, senden Sie eine HTTP-PATCH-Anfrage mit dem Abfrageparameter 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"
    }
  }'

Volume-Pool löschen

Bevor Sie einen Volume-Pool löschen, müssen Sie alle untergeordneten Volumes löschen, die im Pool bereitgestellt wurden. So löschen Sie einen Volume-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 mit der REST API verwalten

Wenn Sie Filestore-Agent-Volumes ohne GKE über Ihre eigene Orchestrierungsplattform für den Speicher verwenden möchten, können Sie einzelne Volumes direkt über die REST API bereitstellen und verwalten.

REST API

Ersetzen Sie in jeder der folgenden Anfragen:

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

Volume erstellen

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

Die Bereitstellung des Volumes dauert weniger als eine Sekunde. Die API gibt die Volume-Ressource direkt zurück:

{
  "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 zurückgegebenen Werte in mountPoint:

  • ipAddress: die interne IP-Adresse des NFS-Bereitstellungsendpunkts in Ihrem VPC-Netzwerk.
  • mountName: Die zu mountende NFS-Exportpfadkomponente.

Volume-Details abrufen

So rufen Sie Details zu einem vorhandenen Volume auf, einschließlich des 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"

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 löschen

Wenn eine Agent-Sitzung beendet wird oder eine temporäre Sandbox beendet wird, löschen Sie das Volume, um das Kontingent im Pool zurückzugewinnen:

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"

Nächste Schritte