Sebagian atau seluruh informasi di halaman ini mungkin tidak berlaku untuk Cloud de Confiance dari S3NS. Lihat Perbedaan dengan Google Cloud untuk mengetahui detail selengkapnya.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Mengotomatiskan penyesuaian performa dengan profil Cloud Storage FUSE

Autopilot Standard

Dokumen ini menjelaskan cara Anda dapat menyetel performa driver CSI Cloud Storage FUSE secara otomatis dan mempercepat akses data workload AI/ML Anda dengan menggunakan profil Cloud Storage FUSE di Google Kubernetes Engine (GKE).

Profil Cloud Storage FUSE mengotomatiskan proses penyesuaian performa penting. Daripada menyesuaikan setelan secara manual, Anda dapat menerapkan profil yang telah ditentukan sebelumnya yang mengonfigurasi driver CSI untuk Anda. Untuk aplikasi AI/ML Anda, penggunaan profil ini dapat menghasilkan waktu pelatihan dan inferensi yang lebih cepat dengan overhead operasional yang lebih rendah.

Dokumen ini ditujukan untuk Developer aplikasi dan Engineer machine learning (ML) yang ingin meningkatkan performa aplikasi mereka tanpa keahlian penyesuaian penyimpanan mendalam. Untuk mempelajari lebih lanjut peran umum, lihat Peran dan tugas pengguna GKE umum.

Sebelum membaca dokumen ini, pastikan Anda memahami dasar-dasar Cloud Storage, Kubernetes, dan driver CSI Cloud Storage FUSE. Selain itu, tinjau persyaratan untuk menggunakan driver CSI Cloud Storage FUSE.

Manfaat menggunakan profil Cloud Storage FUSE

Untuk mengotomatiskan penyesuaian performa untuk workload AI/ML, profil Cloud Storage FUSE menggunakan konfigurasi Cloud Storage FUSE yang telah ditentukan sebelumnya dan menerapkan setelan tambahan khusus GKE. Setelan ini didasarkan pada praktik terbaik penyesuaian performa Cloud Storage FUSE. Menggunakan profil standar memberikan manfaat berikut:

Penyesuaian performa yang disederhanakan: gunakan profil Cloud Storage FUSE yang telah ditentukan sebelumnya untuk menerapkan konfigurasi yang dioptimalkan untuk workload AI/ML umum, seperti pelatihan, penyajian, dan checkpointing.
Pengoptimalan dinamis yang sadar resource: menggunakan profil Cloud Storage FUSE memungkinkan driver CSI menyesuaikan ukuran cache secara otomatis dan memilih media cache yang optimal, seperti RAM atau SSD Lokal, berdasarkan karakteristik bucket atau subdirektori, seperti ukuran, jumlah objek, dan jenis lokasi, batas sidecar, serta resource yang tersedia di node Anda.
Performa baca yang dipercepat: saat Anda menggunakan profil gcsfusecsi-serving, GKE akan otomatis mengaktifkan Cache Cepat untuk meningkatkan performa baca bagi beban kerja penayangan Anda.
Insight penyesuaian performa: Anda mendapatkan insight tentang keputusan penyesuaian otomatis melalui log terstruktur yang menjelaskan sinyal input dari lingkungan Anda dan konfigurasi yang dihasilkan yang diterapkan oleh driver. Untuk mengetahui informasi selengkapnya, lihat Melihat insight rekomendasi

Seiring berkembangnya praktik terbaik Cloud Storage FUSE, profil akan diupdate dari waktu ke waktu melalui rilis GKE baru.

Batasan

Anda tidak dapat menggunakan profil Cloud Storage FUSE dengan volume sementara CSI Cloud Storage FUSE.
Profil tidak mendukung pemasangan dinamis, tempat Anda menentukan garis bawah (_) untuk memasang semua bucket yang dapat diakses oleh ServiceAccount Kubernetes.
Mengganti image file bantuan dengan image file bantuan pribadi kustom tidak didukung. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi image pribadi untuk container sidecar.

Persyaratan

Cluster GKE Anda harus menjalankan versi 1.35.1-gke.1616000 atau yang lebih baru.
Cluster Anda harus mengaktifkan driver CSI Cloud Storage FUSE. Jika Anda membuat cluster baru, atau mengaktifkan driver di cluster yang sudah ada, lihat langkah-langkah berikut dalam dokumen untuk menyiapkan driver CSI Cloud Storage FUSE untuk GKE:

Biaya

Selain biaya GKE dan Cloud Storage standar yang terkait dengan Driver CSI Cloud Storage FUSE, penggunaan profil Cloud Storage FUSE menimbulkan biaya berikut.

Biaya pemindaian bucket

Profil Cloud Storage FUSE melakukan pemindaian latar belakang pada bucket atau subdirektori Anda. Secara default, pemindaian ini terjadi setiap tujuh hari. Pemindaian bucket menimbulkan biaya operasi Kelas A Cloud Storage untuk mencantumkan objek.

Biaya Rapid Cache

Profil gcsfusecsi-serving otomatis mengaktifkan Cache Cepat, yang ditagih sesuai dengan harga Cache Cepat Cloud Storage. Untuk menghindari tagihan instance cache saat tidak lagi diperlukan, lihat Kontrol biaya.

Sebelum memulai

Sebelum memulai, pastikan Anda telah melakukan tugas berikut:

Aktifkan Cloud Storage API dan Google Kubernetes Engine API.

Aktifkan API

Jika ingin menggunakan Google Cloud CLI untuk tugas ini, instal lalu lakukan inisialisasi gcloud CLI. Jika sebelumnya Anda telah menginstal gcloud CLI, dapatkan versi terbaru dengan menjalankan perintah gcloud components update. gcloud CLI versi sebelumnya mungkin tidak mendukung menjalankan perintah dalam dokumen ini.
Catatan: Untuk penginstalan gcloud CLI yang ada, pastikan untuk menyetel properti compute/region. Jika Anda terutama menggunakan cluster zona, tetapkan compute/zone. Dengan menyetel lokasi default, Anda dapat menghindari error di gcloud CLI yang seperti ini: One of [--zone, --region] must be supplied: Please specify location. Anda mungkin perlu menentukan lokasi dalam perintah tertentu jika lokasi cluster Anda berbeda dengan lokasi default yang Anda tetapkan.

Pilih Cloud de Confiance by S3NS region yang sesuai dengan kebutuhan Anda. Meskipun kami merekomendasikan pembuatan cluster GKE dan bucket Cloud Storage di region yang sama untuk mengoptimalkan performa dan biaya, tindakan ini wajib dilakukan saat Anda menggunakan profil gcsfusecsi-serving atau berencana mengaktifkan Rapid Cache.
Pastikan Anda memiliki bucket Cloud Storage yang sudah ada dan berisi set data, model, atau checkpoint untuk beban kerja AI/ML Anda. Jika Anda perlu membuat bucket, lihat Membuat bucket.

Pilih profil performa

Pilih profil yang paling sesuai dengan workload Anda. Setiap profil sesuai dengan StorageClass yang telah diinstal sebelumnya di cluster Anda. Untuk mengetahui definisi mendetail tentang profil Cloud Storage FUSE, lihat referensi konfigurasi StorageClass yang sesuai.

Profil	Nama StorageClass	Dioptimalkan untuk	Fitur utama
Pelatihan	`gcsfusecsi-training`	Pembacaan dengan throughput tinggi	Mengoptimalkan latensi data untuk GPU dan TPU selama pelatihan pada set data besar.
Checkpointing	`gcsfusecsi-checkpointing`	Penulisan dengan throughput tinggi	Meminimalkan waktu yang diperlukan untuk menyimpan checkpoint besar, sehingga mengurangi jeda pelatihan.
Aktif	`gcsfusecsi-serving`	Akses dan caching data	Mengaktifkan Cache Cepat secara default untuk mempercepat operasi baca.

Anda dapat memverifikasi StorageClass yang diinstal di cluster dengan menjalankan perintah berikut:

kubectl get sc -l gke-gcsfuse/profile=true

Mengonfigurasi izin IAM

Beri izin Agen Layanan GKE untuk menganalisis bucket Cloud Storage Anda dan mengelola Rapid Cache.

Ganti placeholder berikut saat menjalankan perintah di bagian ini:

GCS_PROJECT: project ID yang berisi bucket Cloud Storage Anda.
PROJECT_NUMBER: nomor project project cluster GKE Anda.
BUCKET_NAME: nama bucket Cloud Storage Anda.

Pilih salah satu opsi berikut yang sesuai dengan profil dan kebutuhan penggunaan Anda.

Opsi A: Peran khusus (Direkomendasikan)

Opsi ini diperlukan untuk profil Penayangan, atau jika Rapid Cache digunakan. Jika Anda menggunakan profil Penayangan atau berencana mengaktifkan Cache Cepat secara manual untuk profil lain, Anda harus memberikan izin untuk mengelola cache tersebut.

Buat peran IAM kustom yang memungkinkan pemindaian objek dan pembuatan cache Rapid Cache:

gcloud iam roles create gke.gcsfuse.profileUser \
  --project=GCS_PROJECT \
  --title="GKE GCSFuse Profile User" \
  --description="Allows scanning Cloud Storage buckets for objects, retrieving bucket metadata, and creating caches." \
  --permissions="storage.objects.list,storage.buckets.get,storage.anywhereCaches.create,storage.anywhereCaches.get,storage.anywhereCaches.list,storage.anywhereCaches.update"

Ikat peran khusus ke agen Layanan GKE untuk bucket tertentu Anda:

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
  --project=GCS_PROJECT \
  --member="serviceAccount:service-PROJECT_NUMBER@container-engine-robot.s3ns-system.iam.gserviceaccount.com" \
  --role="projects/GCS_PROJECT/roles/gke.gcsfuse.profileUser"

Opsi B: Peran standar untuk profil Pelatihan dan Checkpoint

Jika Anda hanya menggunakan profil Pelatihan atau Checkpointing dan tidak berencana menggunakan Rapid Cache, jalankan perintah berikut:

gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --project=GCS_PROJECT \
    --member="serviceAccount:service-PROJECT_NUMBER@container-engine-robot.s3ns-system.iam.gserviceaccount.com" \
    --role="roles/storage.legacyBucketReader"

Men-deploy workload dengan profil Cloud Storage FUSE

Ikuti langkah-langkah berikut untuk men-deploy workload dengan profil Cloud Storage FUSE.

Buat manifes PersistentVolume (PV) yang mereferensikan salah satu StorageClass profil Cloud Storage FUSE:
```
apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: STORAGECLASS_NAME
  mountOptions:
    - only-dir=BUCKET_DIR_PATH # Optional
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME
```
Ganti kode berikut:
- STORAGECLASS_NAME: nama StorageClass profil yang ingin Anda gunakan. Nilainya harus berupa gcsfusecsi-training, gcsfusecsi-checkpointing, atau gcsfusecsi-serving.
- BUCKET_DIR_PATH: (opsional) jalur dalam bucket Cloud Storage, jika Anda memasang direktori tertentu. Jika ditentukan, GKE akan memindai jalur ini untuk pengoptimalan. Jika dihilangkan, GKE akan memindai seluruh bucket.
- BUCKET_NAME: nama bucket Cloud Storage yang Anda tentukan saat mengonfigurasi akses ke bucket Cloud Storage.

Buat PersistentVolumeClaim (PVC) yang meminta StorageClass yang sama dengan PV Anda:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
  namespace: NAMESPACE
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  volumeName: my-pv
  storageClassName: STORAGECLASS_NAME

Ganti kode berikut:

NAMESPACE: namespace tempat Anda ingin men-deploy Pod.
STORAGECLASS_NAME: nama StorageClass seperti yang tercantum di PV Anda.

Gunakan PVC di Deployment Anda:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
  namespace: NAMESPACE
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
      annotations:
        gke-gcsfuse/volumes: "true"
    spec:
      serviceAccountName: KSA_NAME
      containers:
      - name: my-container
        image: busybox
        volumeMounts:
        - name: my-gcs-volume
          mountPath: "/data"
      volumes:
      - name: my-gcs-volume
        persistentVolumeClaim:
          claimName: my-pvc

Ganti kode berikut:

NAMESPACE: namespace tempat Anda ingin men-deploy Pod.
KSA_NAME: nama ServiceAccount Kubernetes yang Anda buat saat mengonfigurasi akses ke bucket Cloud Storage.

Setelah di-deploy, driver CSI secara otomatis menghitung ukuran cache dan opsi pemasangan yang optimal berdasarkan resource node Anda, seperti GPU atau TPU, memori, SSD Lokal, ukuran bucket atau subdirektori, dan batas resource sidecar.

Memverifikasi pengoptimalan otomatis

Proses latar belakang GKE secara otomatis menganalisis bucket Anda, dan menyinkronkan Rapid Cache (jika digunakan).

Periksa status pemindaian bucket dan cache

Setelah membuat PV, ikuti langkah-langkah berikut untuk memeriksa status pemindaian bucket dan cache. Anda tidak perlu menunggu Pod di-deploy.

Periksa status PV:
```
kubectl describe pv my-pv
```

Pada output, pastikan peristiwa ScanOperationSucceeded muncul. Outputnya mirip dengan hal berikut:

Normal  ScanOperationSucceeded  gke-gcsfuse-scanner  Bucket scan completed successfully for bucket "my-bucket", directory "my-dir": "526893" objects, "57690897566" bytes

Jika Anda menggunakan profil gcsfusecsi-serving, pastikan peristiwa AnywhereCacheSyncSucceeded muncul setelah lapisan caching siap. Outputnya mirip dengan hal berikut ini:
```
Normal  AnywhereCacheSyncSucceeded  gke-gcsfuse-scanner  Anywhere Cache sync succeeded for PV "my-pv": us-central1-c:running
```
Catatan: Pembuatan Rapid Cache dapat memerlukan waktu beberapa menit hingga beberapa jam. Workload Anda tidak diblokir selama waktu ini dan dapat membaca data langsung dari bucket hingga cache beroperasi. Untuk mengetahui informasi selengkapnya, lihat Membuat cache.

Pastikan anotasi PV diperbarui dengan hasil pemindaian:

gke-gcsfuse/bucket-scan-status: completed
gke-gcsfuse/bucket-scan-num-objects: 526893
gke-gcsfuse/bucket-scan-total-size-bytes: 57690897566
gke-gcsfuse/bucket-scan-location-type: multi-region
gke-gcsfuse/bucket-scan-hns-enabled: true
gke-gcsfuse/bucket-scan-last-updated-time: 2025-12-10T22:48:38Z

Periksa status Pod

Setelah Anda men-deploy Pod, jalankan perintah berikut:

kubectl get pods -n NAMESPACE

Ganti NAMESPACE dengan namespace tempat Anda men-deploy Pod.

Pods Anda kini harus berstatus RUNNING, dengan praktik terbaik performa diterapkan secara otomatis. Jika Pod Anda menampilkan status SchedulingGated, hal ini menunjukkan bahwa GKE masih memindai bucket atau subdirektori Anda. Pod tetap dalam status ini hingga pengontrol CSI menyelesaikan pemindaian dan memperbarui PV.

Untuk memahami keputusan penyesuaian spesifik yang dicatat oleh driver setelah Pod dimulai, lihat Melihat insight rekomendasi.

Jika Anda mengalami error, lihat bagian Pemecahan masalah.

Referensi konfigurasi StorageClass

Bagian ini menyediakan manifes StorageClass untuk profil Cloud Storage FUSE yang telah diinstal sebelumnya, dan referensi mendetail untuk opsi pemasangan dan parameter yang digunakan oleh Profil. Konfigurasi ini memungkinkan driver gcsfuse.csi.storage.gke.io mengotomatiskan penyesuaian performa dan pengelolaan resource untuk workload AI/ML Anda.

Pelatihan

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-training
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-training
parameters:
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

Checkpointing

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-checkpointing
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-checkpointing
  - read_ahead_kb=1024
parameters:
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

Aktif

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gcsfusecsi-serving
  labels:
    gke-gcsfuse/profile: "true"
provisioner: gcsfuse.csi.storage.gke.io
mountOptions:
  - profile:aiml-serving
  - read_ahead_kb=131072
  - file-cache:max-size-mb:0
  - read:enable-buffered-read:true
  - read:global-max-blocks:80
parameters:
  anywhereCacheZones: "*"
  anywhereCacheAdmissionPolicy: "admit-on-first-miss"
  anywhereCacheTTL: "1h"
  skipCSIBucketAccessCheck: "true"
  gcsfuseMetadataPrefetchOnMount: "true"
  fuseFileCacheMediumPriority: "gpu:ram|lssd,tpu:ram,general_purpose:ram|lssd"
  fuseMemoryAllocatableFactor: "0.7"
  fuseEphemeralStorageAllocatableFactor: "0.85"
  bucketScanResyncPeriod: "168h"
  bucketScanTimeout: "2m"

Profil menggunakan opsi pemasangan dan parameter berikut untuk driver gcsfuse.csi.storage.gke.io:

mountOptions:
- profile: menerapkan serangkaian pengoptimalan Cloud Storage FUSE yang telah ditentukan sebelumnya yang disesuaikan untuk workload AI/ML. Nilai yang valid untuk profil yang sudah diinstal adalah aiml-training, aiml-checkpointing, dan aiml-serving.
- read_ahead_kb: menentukan ukuran buffer baca-depan dalam kilobyte (KB). Opsi ini memungkinkan Cloud Storage FUSE melakukan pengambilan data terlebih dahulu dari Cloud Storage, sehingga berpotensi meningkatkan performa baca untuk pola akses berurutan.
- file-cache:max-size-mb: untuk profil Penayangan, menentukan ukuran maksimum dalam mebibyte (MiB) untuk cache file. Dalam melayani beban kerja, saat model biasanya dimuat ke memori GPU atau TPU hanya sekali, parameter ini disetel ke 0 untuk menonaktifkan cache file Cloud Storage FUSE lokal, yang membantu mencegah I/O disk yang berlebihan dan menghemat penyimpanan lokal.
- read:enable-buffered-read: untuk profil Penayangan, memungkinkan Cloud Storage FUSE mengelola buffer internalnya sendiri, yang membantu mengurangi jumlah panggilan sistem kecil yang mahal antara aplikasi dan kernel.
- read:global-max-blocks: untuk profil Penayangan, membatasi jumlah total blok memori serentak yang digunakan untuk pembacaan yang di-buffer. Opsi ini membantu mencegah proses FUSE menggunakan semua RAM yang tersedia saat melayani beberapa permintaan.
parameters:
- skipCSIBucketAccessCheck: jika disetel ke "true", akan membuat driver CSI melewati pemeriksaan akses bucket awal. Parameter ini membantu mengurangi panggilan ke Security Token Service untuk menghindari potensi masalah kuota.
- gcsfuseMetadataPrefetchOnMount: jika disetel ke "true", mengarahkan driver CSI untuk memulai prefetching metadata objek dari Cloud Storage ke dalam cache lokal segera setelah volume di-mount. Parameter ini dapat mempercepat akses pertama ke file.
- fuseFileCacheMediumPriority: menentukan urutan prioritas untuk media penyimpanan yang digunakan oleh file cache Cloud Storage FUSE. Hal ini memungkinkan penentuan preferensi yang berbeda untuk node dengan GPU, TPU, atau node serbaguna. Opsi media mencakup ram dan lssd (SSD Lokal, jika tersedia dan diaktifkan).
- fuseMemoryAllocatableFactor: menentukan dalam format string pecahan yang membatasi memori maksimum yang dapat digunakan oleh cache Cloud Storage FUSE, relatif terhadap total memori yang dapat dialokasikan node dan batas memori sidecar.
- fuseEphemeralStorageAllocatableFactor: membatasi penggunaan cache Cloud Storage FUSE untuk penyimpanan efemeral di node (seperti SSD Lokal untuk caching file), relatif terhadap penyimpanan efemeral yang dapat dialokasikan di node atau penyimpanan efemeral sidecar yang dibatasi untuk caching.
- bucketScanResyncPeriod: menetapkan interval waktu saat PV dipindai ulang untuk mendeteksi perubahan yang dilakukan pada bucket Cloud Storage.
- bucketScanTimeout: durasi maksimum yang diizinkan untuk satu operasi pemindaian bucket. Jika pemindaian melebihi waktu ini, hasil sebagian dapat digunakan.
- anywhereCacheZones: menentukan daftar zona yang didukung yang dipisahkan koma tempat cache Rapid Cache dibuat, misalnya, "us-central1-a,us-central1-b". Untuk menggunakan semua zona yang tersedia untuk cluster, gunakan "*" sebagai nilai. Jika disetel ke "none" atau tidak ditentukan, Cache Cepat akan dinonaktifkan.
- anywhereCacheTTL: Time To Live (TTL) untuk data yang disimpan di cache Rapid Cache, diukur dari akses terakhir. Jika Anda mengubah nilai ini, instance Rapid Cache yang ada akan diperbarui dengan TTL baru.
- anywhereCacheAdmissionPolicy: menentukan kapan data dimasukkan ke dalam cache Cepat setelah baca tidak ada (saat data yang diminta tidak ditemukan dalam cache). Opsi mencakup "admit-on-first-miss", yang memasukkan data pada miss baca pertama, atau "admit-on-second-miss", yang memasukkan data hanya pada miss baca kedua untuk objek yang sama. Jika Anda mengubah nilai ini, instance Rapid Cache yang ada akan diperbarui dengan kebijakan baru.

Opsional: Menyesuaikan konfigurasi profil

Anda dapat menyesuaikan setelan tertentu dalam profil sambil tetap mendapatkan manfaat dari konfigurasi dasarnya. Gunakan opsi berikut untuk menyesuaikan profil tanpa membuat StorageClass baru.

Mengganti opsi dan parameter pemasangan

Untuk mengubah perilaku tertentu, tambahkan opsi pemasangan ke kolom spec.mountOptions, atau parameter CSI ke kolom spec.csi.volumeAttributes di PV Anda. GKE menerapkan setelan manual Anda di atas setelan default profil.

Contoh berikut menunjukkan cara mengganti opsi pemasangan read_ahead_kb dan menonaktifkan parameter gcsfuseMetadataPrefetchOnMount di profil Penayangan.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv-override
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: gcsfusecsi-serving
  mountOptions:
  - read_ahead_kb=2048 # Overrides the profile's default.
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: my-gcs-bucket
    volumeAttributes:
      gcsfuseMetadataPrefetchOnMount: "false" # Overrides the profile's default.

Kasus penggunaan umum mencakup:

Untuk mengaktifkan Cache Cepat untuk profil Pelatihan, tambahkan parameter anywhereCacheZones langsung ke spesifikasi PV Anda.
Untuk menyesuaikan perilaku Cloud Storage FUSE tertentu, seperti meningkatkan ukuran read_ahead_kb, guna memenuhi persyaratan unik dari workload tertentu.

Saat Anda mengonfigurasi ukuran cache secara manual, pertimbangkan hal berikut:

Menentukan ukuran cache manual akan menggantikan ukuran dinamis otomatis hanya untuk komponen tertentu tersebut. Penyesuaian ukuran dinamis berlanjut untuk semua komponen lainnya berdasarkan upaya terbaik dalam anggaran resource yang tersisa.
Menetapkan opsi metadata-cache atau file-cache, seperti metadata-cache:stat-cache-max-size-mb, tidak akan menonaktifkan perhitungan otomatis untuk jenis cache lainnya.
Jika menentukan file-cache:max-size-mb secara manual, Anda juga harus mengonfigurasi volume cache baca kustom. Hal ini membantu memastikan bahwa media penyimpanan dengan kapasitas yang memadai ditentukan secara eksplisit untuk ukuran cache kustom Anda.

Melewati pemindaian bucket dengan anotasi

Anda dapat melewati proses pemindaian bucket otomatis dengan memberikan metrik ukuran dan jumlah objek Anda sendiri menggunakan anotasi. Driver CSI menggunakan nilai-nilai ini untuk menghitung konfigurasi performa yang optimal tanpa memindai bucket.

Contoh berikut menunjukkan cara menambahkan anotasi gke-gcsfuse/bucket-scan-status: "override" ke PV Anda, beserta anotasi metrik tertentu.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv-override
  annotations:
    gke-gcsfuse/bucket-scan-status: "override"
    gke-gcsfuse/bucket-scan-num-objects: 19238
    gke-gcsfuse/bucket-scan-total-size-bytes: 94837465
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  persistentVolumeReclaimPolicy: Retain
  storageClassName: STORAGECLASS_NAME
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME

Kasus penggunaan umum mencakup:

Jika sudah mengetahui ukuran bucket dan jumlah objek, terutama untuk workload inferensi yang datanya jarang berubah, Anda dapat melewati waktu pemindaian saat startup.
Jika Cloud Storage API tidak tersedia untuk sementara, anotasi ini dapat membantu Anda mempertahankan performa saat layanan yang mendasarinya sedang diperbaiki.

Pemecahan masalah

Gunakan informasi berikut untuk memantau status profil Cloud Storage FUSE dan menyelesaikan masalah umum yang terjadi selama pemindaian bucket dan sinkronisasi cache.

Parameter konfigurasi tidak valid (`InvalidArgument`)

Tugas pengoptimalan latar belakang gagal dimulai karena satu atau beberapa parameter yang diberikan dalam manifes Anda tidak valid.

Gejala

PV menampilkan peristiwa ScanOperationStartError atau AnywhereCacheSyncError dengan pesan yang berisi rpc error: code = InvalidArgument. Contohnya mencakup:

Bucket scan timeout configuration error: rpc error: code = InvalidArgument desc = invalid duration format for "INVALID_DURATION".
Anywhere Cache sync failed for PV "PV_NAME": rpc error: code = InvalidArgument desc = failed to get anywhere cache "CACHE_NAME" ... invalid anywhere cache "CACHE_NAME" provided.

Penyebab

Satu atau beberapa parameter di kolom spec.csi.volumeAttributes PV Anda diformat dengan salah atau berisi nilai yang tidak dapat diuraikan oleh sistem.

Resolusi

Perbaiki nilai parameter yang tidak valid dalam manifes PV Anda dan deploy ulang PV. Pastikan semua nilai durasi (seperti bucketScanTimeout) menggunakan format yang benar (misalnya, 2m atau 10m) dan semua setelan khusus profil cocok dengan nilai yang didukung dan valid.

Izin ditolak saat memindai bucket Cloud Storage

GKE tidak dapat mengakses bucket Cloud Storage yang ditentukan untuk melakukan analisis performa yang diperlukan.

Gejala

PV menampilkan peristiwa ScanOperationStartError dengan pesan Error 403: Forbidden yang menunjukkan bahwa pemanggil tidak memiliki akses storage.buckets.get.

Penyebab

Agen Layanan GKE tidak memiliki izin IAM yang diperlukan, atau nama bucket salah.

Resolusi

Pastikan nama bucket di kolom volumeHandle PV Anda sudah benar dan bucket tersebut ada.
Pastikan izin GKE Service Agent diberikan ke identitas service-PROJECT_NUMBER@container-engine-robot.s3ns-system.iam.gserviceaccount.com untuk bucket tertentu. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi izin IAM.

Lokasi Rapid Cache tidak cocok

Cache Rapid Cache tidak dapat dibuat karena zona yang diminta tidak kompatibel dengan lokasi bucket.

Gejala

PV menampilkan peristiwa AnywhereCacheSyncWarning dengan pesan: Invalid zone. Rapid Cache isn't available in the requested zone.

Penyebab

Cache Cepat harus dibuat di zona yang berada dalam lokasi regional bucket. Error ini biasanya terjadi saat cluster GKE dan bucket Cloud Storage Anda berada di region yang berbeda.

Resolusi

Pindahkan bucket Cloud Storage Anda ke region yang cocok dengan lokasi cluster GKE dan deploy ulang PV.

Waktu pemindaian bucket habis

Analisis bucket Cloud Storage membutuhkan waktu lebih lama daripada waktu tunggu yang dikonfigurasi, sehingga menghasilkan hasil pengoptimalan parsial.

Gejala

PV menampilkan peristiwa ScanOperationTimedOut. PV diberi anotasi dengan hasil parsial untuk jumlah objek dan ukuran total.

Penyebab

Bucket berisi sejumlah besar objek (biasanya beberapa juta) yang tidak dapat sepenuhnya dicantumkan dalam waktu tunggu default dua menit.

Resolusi

Tetapkan nilai yang lebih besar untuk kolom bucketScanTimeout di bagian spec.csi.volumeAttributes PV Anda, misalnya, 10m.
Jika ukuran bucket bersifat statis, lewati pemindaian dengan memberikan jumlah dan ukuran objek secara manual.

Cache metadata dibatasi oleh anggaran memori

Driver membatasi ukuran cache metadata agar sesuai dengan resource yang tersedia di node, yang dapat mengurangi performa.

Gejala

Log berisi pesan yang menyatakan bahwa ukuran cache stat metadata yang diperlukan dibatasi hingga anggaran memori Cloud Storage FUSE yang tersedia.

Penyebab

Cache metadata untuk jumlah objek di bucket Anda melebihi memori yang dialokasikan ke sidecar Cloud Storage FUSE atau memori yang tersedia di node.

Resolusi

Gunakan opsi pemasangan only-dir untuk mencakup volume ke subdirektori yang lebih kecil dengan lebih sedikit objek.
Tingkatkan batas memori untuk container sidecar Cloud Storage FUSE.
- Jika batas sidecar sudah cukup, gunakan jenis node dengan memori yang dapat dialokasikan lebih besar.

Cache file dinonaktifkan karena batas resource

GKE menonaktifkan cache file lokal karena tidak dapat menemukan media penyimpanan yang sesuai dengan ruang yang cukup.

Gejala

Log menampilkan peringatan: No suitable file cache medium found or requirement exceeded limits for all options.

Penyebab

Ukuran cache file yang dihitung melebihi RAM node yang tersedia dan penyimpanan SSD Lokal yang tersedia.

Resolusi

Gunakan opsi pemasangan only-dir untuk mencakup volume ke subdirektori yang lebih kecil dengan lebih sedikit objek.
Tingkatkan batas resource sidecar Cloud Storage FUSE.
Gunakan jenis node dengan memori yang lebih besar atau aktifkan SSD Lokal di node pool Anda.

Memantau status menggunakan peristiwa PersistentVolume

GKE mencatat peristiwa dan error konfigurasi utama ke PV. Untuk memeriksa peristiwa ini, jalankan perintah berikut:

kubectl describe pv PV_NAME

Setelah pemindaian bucket berhasil, Anda akan melihat peristiwa ScanOperationSucceeded. Jika Anda menggunakan profil gcsfusecsi-serving, Anda akan melihat peristiwa AnywhereCacheSyncSucceeded setelah lapisan caching beroperasi.

Memantau status menggunakan log driver CSI

Driver CSI Cloud Storage FUSE mencatat keputusan konfigurasi dan insight performa yang mendetail. Untuk melihat log ini di Cloud Logging, gunakan kueri berikut:

resource.type="k8s_container"
resource.labels.pod_name=~"gcsfusecsi-node-.*"

Melihat insight rekomendasi

Untuk memahami sinyal input dan keputusan spesifik yang dibuat oleh logika penyesuaian otomatis, telusuri string GCSFuseCSIRecommendation di log driver CSI. Payload JSON yang dihasilkan memberikan metrik mendetail, termasuk berikut ini:

inputSignals: jumlah objek bucket, total ukuran data, dan resource node yang tersedia (RAM dan penyimpanan sementara).
decision: ukuran cache yang dihitung akhir dan media penyimpanan yang dipilih (ram atau lssd).

{
  "insertId": "INSERT_ID",
  "jsonPayload": {
    "decision": {
      "fileCacheBytes": 300000000,
      "fileCacheMedium": "lssd",
      "metadataStatCacheBytes": 4500,
    },
    "target": {
      "nodeName": "NODE_NAME",
      "pvName": "PV_NAME",
      "podName": "POD_NAME"
    },
    "message": "GCSFuseCSIRecommendation: Recommended cache configs for PV PV_NAME and Pod POD_NAME: FileCache: 287MiB (lssd) | MetadataStatCache: 1MiB | Expand for full details",
    "inputSignals": {
      "requiredFileCacheBytes": 300000000,
      "fuseBudgetMemoryBytes": 187904819,
      "sidecarLimitMemoryBytes": 268435456,
      "nodeType": "gpu",
      "bucketTotalObjects": 3,
      "nodeAllocatableMemoryBytes": 191291998208,
      "bucketTotalDataSizeBytes": 300000000,
      "bucketLocationType": "multi-region",
      "bucketHNSEnabled": true,
      "sidecarLimitEphemeralStorageBytes": 0,
      "requiredMetadataStatCacheBytes": 4500,
      "nodeAllocatableEphemeralStorageBytes": 1317908854882,
      "nodeHasEphemeralStorageLSSD": true,
      "fuseBudgetEphemeralStorageBytes": 1120222526649
    }
  },
  ...
}

Pembersihan

Agar akun Cloud de Confiance by S3NS Anda tidak dikenai biaya untuk resource yang dibuat dalam panduan ini, lakukan langkah-langkah berikut:

Hapus Deployment:
```
kubectl delete deployment my-deployment -n NAMESPACE
```
Ganti NAMESPACE dengan namespace Kubernetes tempat Anda membuat Deployment.
Hapus PersistentVolumeClaim:
```
kubectl delete pvc my-pvc -n NAMESPACE
```
Ganti NAMESPACE dengan namespace Kubernetes tempat Anda membuat PVC.
Hapus PersistentVolume:
```
kubectl delete pv my-pv
```
Jika Anda menggunakan profil gcsfusecsi-serving atau mengaktifkan secara manual Cache Cepat, ikuti petunjuk untuk Menonaktifkan cache agar tidak dikenai biaya untuk instance cache.

Langkah berikutnya

Pelajari lebih lanjut driver CSI Cloud Storage FUSE.
Pelajari cara mengoptimalkan driver CSI Cloud Storage FUSE secara manual untuk performa.

Mengotomatiskan penyesuaian performa dengan profil Cloud Storage FUSE

Manfaat menggunakan profil Cloud Storage FUSE

Batasan

Persyaratan

Biaya

Biaya pemindaian bucket

Biaya Rapid Cache

Sebelum memulai

Pilih profil performa

Mengonfigurasi izin IAM

Opsi A: Peran khusus (Direkomendasikan)

Opsi B: Peran standar untuk profil Pelatihan dan Checkpoint

Men-deploy workload dengan profil Cloud Storage FUSE

Memverifikasi pengoptimalan otomatis

Periksa status pemindaian bucket dan cache

Periksa status Pod

Referensi konfigurasi StorageClass

Pelatihan

Checkpointing

Aktif

Opsional: Menyesuaikan konfigurasi profil

Mengganti opsi dan parameter pemasangan

Melewati pemindaian bucket dengan anotasi

Pemecahan masalah

Parameter konfigurasi tidak valid (InvalidArgument)

Izin ditolak saat memindai bucket Cloud Storage

Lokasi Rapid Cache tidak cocok

Waktu pemindaian bucket habis

Cache metadata dibatasi oleh anggaran memori

Cache file dinonaktifkan karena batas resource

Memantau status menggunakan peristiwa PersistentVolume

Memantau status menggunakan log driver CSI

Melihat insight rekomendasi

Pembersihan

Langkah berikutnya

Parameter konfigurasi tidak valid (`InvalidArgument`)