Membuat dan mengelola kumpulan volume

Kumpulan volume adalah resource regional tingkat teratas yang mengelola kumpulan bersama kapasitas penyimpanan dan IOPS untuk project dan jaringan Virtual Private Cloud (VPC) Anda. Dalam kumpulan volume, Anda dapat menyediakan hingga 1 juta volume ringan yang independen untuk sandbox agen AI, ruang kerja developer, atau workload multi-tenant umum.

Sebelum memulai

Selesaikan prasyarat yang dijelaskan dalam Menyiapkan volume agen Filestore.

Membuat kumpulan volume

REST API

Untuk membuat kumpulan volume, kirim permintaan HTTP POST ke endpoint 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"

Ganti kode berikut:

  • PROJECT_ID: Google Cloud Project ID
  • LOCATION: region tempat pool di-deploy, seperti us-central1.
  • VOLUME_POOL_ID: ID untuk pool volume, yang cocok dengan ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$.
  • VPC_NETWORK: nama jaringan VPC yang ada.

Kolom permintaan

Isi permintaan berisi kolom berikut:

Kolom Jenis Wajib Deskripsi
network string Wajib Jalur resource jaringan VPC Anda, dalam format: projects/{project}/global/networks/{network}. Jaringan harus memiliki kebijakan koneksi layanan PSC yang valid.
defaultVolumeQuotaMib int64 Opsional Kuota default per volume dalam MiB. Nilai harus antara 100 MiB dan 102400 MiB (100 GiB). Nilai defaultnya adalah 1024 MiB.
description string Opsional Deskripsi kumpulan volume yang mudah digunakan.
labels map[string, string] Opsional Pasangan nilai kunci yang memungkinkan Anda mengatur dan memfilter resource di Google Cloud.

Respons

Metode ini menampilkan objek operasi yang berjalan lama (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
}

Lakukan polling operasi hingga done menjadi 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"

Ganti kode berikut:

  • PROJECT_ID: Google Cloud Project ID
  • LOCATION: region tempat volume pool di-deploy, seperti us-central1.
  • OPERATION_ID: ID operasi yang ditampilkan dalam respons pembuatan.

Setelah selesai, operasi akan menampilkan objek VolumePool dengan status READY.

Mengelola kumpulan volume

Anda dapat melihat detail tentang kumpulan volume yang ada, mencantumkan kumpulan dalam suatu region, memperbarui konfigurasi seperti label dan kuota kapasitas, atau menghapus kumpulan volume.

REST API

Di setiap permintaan berikut, ganti:

  • PROJECT_ID: Google Cloud Project ID
  • LOCATION: region tempat volume pool di-deploy, seperti us-central1.
  • VOLUME_POOL_ID: ID pool volume.

Mendapatkan informasi tentang kumpulan volume

Untuk mengambil detail tentang kumpulan volume tertentu:

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"

Mencantumkan kumpulan volume

Untuk mencantumkan semua kumpulan volume di region tertentu:

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

Memperbarui kumpulan volume

Untuk memperbarui deskripsi, label, atau kuota default kumpulan volume yang ada, kirim permintaan HTTP PATCH dengan parameter kueri 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"
    }
  }'

Menghapus kumpulan volume

Sebelum menghapus kumpulan volume, Anda harus menghapus semua volume turunan yang disediakan dalam kumpulan tersebut. Untuk menghapus kumpulan volume:

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"

Mengelola volume menggunakan REST API

Jika ingin menggunakan volume agen Filestore tanpa GKE melalui platform orkestrasi Anda sendiri untuk penyimpanan, Anda dapat menyediakan dan mengelola volume satu per satu secara langsung menggunakan REST API.

REST API

Di setiap permintaan berikut, ganti:

  • PROJECT_ID: Google Cloud Project ID
  • LOCATION: region yang berisi kumpulan volume induk.
  • VOLUME_POOL_ID: ID pool volume induk.
  • VOLUME_ID: ID untuk volume, yang cocok dengan ^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$.

Membuat volume

Untuk menyediakan volume individual dalam kumpulan volume, kirim permintaan POST HTTP ke 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"
    }
  }'

Penyediaan volume selesai dalam waktu kurang dari satu detik. API menampilkan resource Volume secara langsung:

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

Perhatikan nilai yang ditampilkan di dalam mountPoint:

  • ipAddress: alamat IP internal endpoint pemasangan NFS dalam jaringan VPC Anda.
  • mountName: komponen jalur ekspor NFS yang akan dipasang.

Mendapatkan detail volume

Untuk melihat detail volume yang ada, termasuk mountPoint-nya:

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"

Mencantumkan volume dalam pool

Untuk mencantumkan semua volume yang disediakan dalam kumpulan 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"

Menghapus volume

Saat sesi agen berakhir atau sandbox sementara dihentikan, hapus volume untuk mendapatkan kembali kuota dalam kumpulan:

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"

Langkah berikutnya