Membuat dan mengelola volume agen Filestore menggunakan REST API

Catatan: Volume agen Filestore tersedia dalam program GA yang Diizinkan (AGA). Untuk meminta akses bagi project Google Cloud Anda, kirimkan formulir permintaan akses volume agen Filestore.

Jika Anda menggunakan volume agen Filestore dengan platform orkestrasi, sandbox berbasis VM, atau lingkungan container non-Google Kubernetes Engine (GKE) Anda sendiri, Anda dapat menyediakan dan mengelola setiap volume di dalam kumpulan volume secara langsung menggunakan Filestore REST API.

Catatan: Jika Anda men-deploy workload di GKE, Anda tidak perlu menyediakan atau mengelola volume secara manual. Driver CSI Filestore dan orkestrasi GKE otomatis mengelola penyediaan volume dari kumpulan volume Anda. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan lingkungan GKE untuk volume agen Filestore.

Sebelum memulai

1. Selesaikan penyiapan jaringan project awal dan Private Service Connect (PSC) di Menyiapkan volume agen Filestore.
2. Buat kumpulan volume regional di Membuat dan mengelola kumpulan volume.

Membuat volume

REST API

Untuk menyediakan volume individual di 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"
    }
  }'

Ganti kode berikut:

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

Penyediaan volume selesai dalam waktu kurang dari satu hingga dua detik. API menampilkan resource Volume secara langsung. Anda juga dapat menentukan kuota volume kustom (quotaMib) dan opsi ekspor NFS dinamis (ipAcls) selama pembuatan 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"
  }
}

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.

Memasang volume

Setelah menyediakan volume, orchestrator Anda dapat memasang ekspor NFSv3 volume langsung ke VM klien atau host container yang terhubung ke jaringan VPC yang sama:

1. Pastikan utilitas klien NFS diinstal di host (misalnya, nfs-common di Debian atau Ubuntu).

2. Buat direktori pemasangan dan pasang volume menggunakan ipAddress dan mountName yang ditampilkan dalam mountPoint 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
   

   Ganti kode berikut:

   • MOUNT_DIR: jalur direktori lokal tempat volume dipasang, seperti /workspace.
   • IP_ADDRESS: nilai mountPoint.ipAddress yang ditampilkan saat membuat atau mengambil volume.
   • MOUNT_NAME: nilai mountPoint.mountName yang ditampilkan saat membuat atau mengambil volume.

Mengelola volume

REST API

Dalam setiap permintaan berikut, ganti:

• PROJECT_ID: Google Cloud Project ID
• LOCATION: region yang berisi kumpulan volume induk.
• VOLUME_POOL_ID: ID kumpulan volume induk.
• VOLUME_ID: ID volume.

Mendapatkan detail volume

Untuk melihat detail volume yang ada, termasuk mountPoint dan state siklus proses saat ini:

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"

Memperbarui kuota volume

Untuk meningkatkan kuota penyimpanan untuk volume aktif, kirim permintaan PATCH HTTP yang menentukan updateMask=quotaMib. Kuota volume hanya dapat ditingkatkan; pengurangan kuota volume tidak didukung:

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"

Memperbarui ACL IP volume

Untuk membatasi akses NFS ke alamat IP klien sandbox tertentu atau memperbarui aturan ekspor IP, kirim permintaan HTTP PATCH yang menentukan 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"

Menghapus volume

Saat sesi agen berakhir atau sandbox sementara dihentikan, hapus volume untuk mengklaim kembali kuota dalam 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"

Meng-clone ruang kerja dengan snapshot volume

Jika Anda sudah memiliki volume pool dalam status READY dan volume sumber yang ada dalam status HOT, Anda dapat membuat snapshot volume untuk mengambil status point-in-time dari agent volume sehingga Anda dapat meng-clone atau membuat cabang ruang kerja nanti.

Catatan: Snapshot volume dikelola menggunakan koleksi resource backups dengan kolom sourceVolume.

REST API

Membuat snapshot volume

1. Kirim permintaan POST HTTP ke endpoint backups.create, dengan menentukan nama resource lengkap volume di kolom sourceVolume dan mengganti SNAPSHOT_ID dengan ID unik untuk 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. Permintaan ini menampilkan operasi yang berjalan lama (LRO). Lakukan polling pada operasi atau buat kueri resource snapshot hingga state-nya menjadi READY sebelum meng-clone volume darinya:

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

Meng-clone volume dari snapshot

Untuk meng-clone volume dari snapshot, snapshot sumber harus berasal dari volume di kumpulan volume yang sama.

1. Kirim permintaan POST HTTP ke endpoint volumes:createFromSource. Teruskan ipAcls dalam isi permintaan untuk mengonfigurasi izin ekspor dan mengaktifkan volume yang di-clone di paket 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"
   

   Ganti kode berikut:

   • SNAPSHOT_ID: ID snapshot sumber di pool volume yang sama.
   • CLONED_VOLUME_ID: ID untuk volume baru yang di-clone.

2. Permintaan ini akan menampilkan operasi yang berjalan lama. Lakukan polling pada 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"
   

3. Setelah operasi selesai, panggil volumes.get (atau periksa respons operasi yang selesai) untuk mengambil mountPoint volume baru (ipAddress dan mountName) sebelum memasang:

   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"
   

Cloning volume dari snapshot selesai dalam 3 detik per GB atau 1,5 detik per 10.000 file.

Memindahkan volume ke tingkat COLD

REST API

Untuk memindahkan ruang kerja yang tidak ada aktivitas ke cold storage, kirim permintaan HTTP PATCH yang mengupdate status volume ke COLD dan menghapus 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"

Untuk memulihkan volume dari tingkat COLD ke tingkat HOT saat sesi agen dilanjutkan:

1. Panggil metode kustom unfreeze, dengan meneruskan ipAcls dalam isi permintaan untuk mengonfigurasi akses klien dan mengaktifkan direktori pemasangan volume di tingkat 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. Permintaan ini akan menampilkan operasi yang berjalan lama. Lakukan polling pada 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"
   

3. Saat volume dipulihkan dari tingkat COLD, Filestore menetapkan endpoint pemasangan NFS baru dari kumpulan volume, sehingga mountPoint.ipAddress dan mountPoint.mountName berubah. Ambil mountPoint yang diperbarui dari respons operasi yang telah selesai atau dengan memanggil volumes.get sebelum memasang ulang 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"
   

Langkah berikutnya

• Mengelola dan memantau kumpulan volume.
• Konfigurasikan lingkungan GKE untuk volume agen Filestore.