Mengakses bucket Cloud Storage dengan driver CSI Cloud Storage FUSE

Filesystem in Userspace (FUSE) adalah antarmuka yang digunakan untuk mengekspor sistem file ke kernel Linux. Cloud Storage FUSE memungkinkan Anda memasang bucket Cloud Storage sebagai sistem file sehingga aplikasi dapat mengakses objek dalam bucket menggunakan operasi IO File yang umum (misalnya membuka, membaca, menulis, menutup), bukan menggunakan API khusus cloud.

Driver CSI Cloud Storage FUSE memungkinkan Anda menggunakan Kubernetes API untuk menggunakan bucket Cloud Storage yang sudah ada sebagai volume. Aplikasi Anda dapat mengupload dan mendownload objek menggunakan semantik sistem file Cloud Storage FUSE. Driver CSI Cloud Storage FUSE memberikan pengalaman yang terkelola sepenuhnya dan didukung oleh driver CSI Google Cloud Storage FUSE open source.

Driver mendukung cara berikut secara native agar Anda dapat mengonfigurasi volume yang didukung Cloud Storage:

Anda dapat menggunakan driver CSI Cloud Storage FUSE dengan cache file untuk meningkatkan performa baca aplikasi yang menangani file kecil dari bucket Cloud Storage. Fitur cache file Cloud Storage FUSE adalah cache baca berbasis klien yang memungkinkan pembacaan file berulang ditayangkan lebih cepat dari penyimpanan cache pilihan Anda. Anda dapat memilih dari berbagai opsi penyimpanan untuk cache baca, termasuk SSD Lokal dan penyimpanan berbasis Persistent Disk, berdasarkan kebutuhan rasio performa-harga Anda. Anda harus memilih untuk mengaktifkan penyimpanan dalam cache file dengan driver CSI Cloud Storage FUSE. Untuk mempelajari lebih lanjut praktik terbaik untuk caching, lihat Performa Cloud Storage FUSE.

Manfaat

  • Driver CSI Cloud Storage FUSE di cluster Anda mengaktifkan deployment dan pengelolaan driver secara otomatis. Driver berfungsi baik di cluster Standard maupun Autopilot.
  • Driver CSI Cloud Storage FUSE tidak memerlukan akses dengan hak istimewa yang biasanya disyaratkan oleh klien FUSE. Hal ini memungkinkan postur keamanan yang lebih baik.
  • Dukungan volume efemeral CSI menyederhanakan konfigurasi dan pengelolaan volume dengan meniadakan kebutuhan akan objek PersistentVolumeClaim dan PersistentVolume.
  • Driver CSI Cloud Storage FUSE mendukung mode akses ReadWriteMany, ReadOnlyMany, dan ReadWriteOnce.
  • Anda dapat menggunakan Workload Identity Federation untuk GKE untuk mengelola autentikasi sekaligus memiliki kontrol terperinci atas cara Pod mengakses objek Cloud Storage. Akses level bucket seragam diperlukan untuk beban kerja baca-tulis saat menggunakan Workload Identity Federation.
  • Jika Anda menjalankan pelatihan ML dan menyalurkan workload dengan framework seperti Ray, PyTorch, Spark, dan TensorFlow, portabilitas dan kemudahan yang disediakan oleh driver CSI Cloud Storage FUSE memungkinkan Anda menjalankan workload secara langsung di cluster GKE tanpa perlu mengubah kode tambahan.
  • Anda dapat membaca objek Cloud Storage dengan cache file diaktifkan untuk meningkatkan performa baca. Cache file mempercepat pembacaan berulang, dengan menayangkan objek dari penyimpanan lokal. Untuk mempelajari lebih lanjut manfaat penyimpanan dalam cache file, baca dokumentasi Cloud Storage FUSE.
  • Dengan Cloud Storage FUSE v.2.4.0 dan cache file diaktifkan, Anda dapat menggunakan fitur download paralel untuk mempercepat pembacaan file besar dari Cloud Storage untuk download multi-thread. Anda dapat menggunakan fitur ini untuk meningkatkan waktu pemuatan model, terutama untuk pembacaan berukuran lebih dari 1 GB (misalnya, hingga dua kali lebih cepat saat memuat Llama2 70B).
  • Anda dapat menggunakan volume Cloud Storage FUSE dalam penampung init.
  • Anda dapat melihat insight metrik untuk Cloud Storage FUSE, termasuk penggunaan sistem file, Cloud Storage, dan cache file.

Sebelum memulai

Sebelum memulai, pastikan Anda telah menjalankan tugas berikut:

  • Aktifkan Google Kubernetes Engine API.
    • Aktifkan Google Kubernetes Engine 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 gcloud components update.
  • Buat bucket Cloud Storage. Untuk meningkatkan performa, tetapkan kolom Location type ke Region, lalu pilih region tempat cluster GKE Anda sedang berjalan.

Batasan

Persyaratan

Untuk menggunakan driver CSI Cloud Storage FUSE, cluster Anda harus memenuhi syarat berikut:

Mengaktifkan driver CSI Cloud Storage FUSE

Untuk membuat cluster Standard dengan driver CSI Cloud Storage FUSE diaktifkan, Anda dapat menggunakan gcloud CLI:

gcloud container clusters create CLUSTER_NAME \
    --addons GcsFuseCsiDriver \
    --cluster-version=VERSION \
    --location=LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog

Ganti kode berikut:

  • CLUSTER_NAME: nama cluster Anda.
  • VERSION: nomor versi GKE. Anda harus memilih 1.24 atau yang lebih baru.
  • LOCATION: lokasi Compute Engine untuk cluster.
  • PROJECT_ID: project ID Anda.

Untuk mengaktifkan driver di cluster Standard yang sudah ada, gunakan perintah gcloud container clusters update:

gcloud container clusters update CLUSTER_NAME \
    --update-addons GcsFuseCsiDriver=ENABLED \
    --location=LOCATION

Ganti kode berikut:

Setelah mengaktifkan driver CSI Cloud Storage FUSE, Anda dapat menggunakan driver tersebut di volume Kubernetes dengan menentukan nama driver dan penyedia: gcsfuse.csi.storage.gke.io.

Mengonfigurasi akses ke bucket Cloud Storage menggunakan GKE Workload Identity Federation for GKE

Agar bucket Cloud Storage Anda dapat diakses oleh cluster GKE menggunakan Workload Identity Federation untuk GKE, ikuti langkah-langkah berikut. Lihat Mengonfigurasi aplikasi untuk menggunakan Workload Identity Federation untuk GKE untuk mengetahui informasi selengkapnya.

  1. Dapatkan kredensial untuk cluster Anda:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=LOCATION

    Ganti kode berikut:

    • CLUSTER_NAME: nama cluster Anda yang telah mengaktifkan Workload Identity Federation untuk GKE.
    • LOCATION: lokasi Compute Engine untuk cluster.

  2. Buat namespace yang akan digunakan untuk Akun Layanan Kubernetes. Anda juga dapat menggunakan namespace default atau namespace apa pun yang sudah ada.

    kubectl create namespace NAMESPACE

    Ganti kode berikut:

    • NAMESPACE: nama namespace Kubernetes untuk Akun Layanan Kubernetes.

  3. Buat Akun Layanan Kubernetes yang akan digunakan aplikasi Anda. Anda juga dapat menggunakan Akun Layanan Kubernetes yang sudah ada di namespace mana pun, termasuk Akun Layanan Kubernetes default.

    kubectl create serviceaccount KSA_NAME \
    --namespace NAMESPACE

    Ganti kode berikut:

    • KSA_NAME: nama ServiceAccount Kubernetes baru Anda.
    • NAMESPACE: nama namespace Kubernetes untuk Akun Layanan Kubernetes.

  4. Berikan salah satu peran IAM untuk Cloud Storage ke Akun Layanan Kubernetes.

    Anda dapat memberikan peran ke Akun Layanan Kubernetes untuk hanya mengakses bucket Cloud Storage tertentu menggunakan perintah berikut:

    gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member "principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME" \
    --role "ROLE_NAME"

    Ganti kode berikut:

    • BUCKET_NAME: nama bucket Cloud Storage Anda.
    • PROJECT_NUMBER: nomor project numerik cluster GKE Anda. Untuk menemukan nomor project Anda, lihat Mengidentifikasi project.
    • PROJECT_ID: project ID cluster GKE Anda.
    • NAMESPACE: nama namespace Kubernetes untuk Akun Layanan Kubernetes.
    • KSA_NAME: nama ServiceAccount Kubernetes baru Anda.
    • ROLE_NAME: peran IAM yang akan ditetapkan ke ServiceAccount Kubernetes Anda.
      • Untuk beban kerja hanya baca, gunakan peran Storage Object Viewer (roles/storage.objectViewer).
      • Untuk beban kerja baca-tulis, gunakan peran Storage Object User (roles/storage.objectUser).

    Jika ingin, Anda juga dapat memberikan peran ke ServiceAccount Kubernetes untuk mengakses semua bucket Cloud Storage di project menggunakan perintah berikut:

    gcloud projects add-iam-policy-binding GCS_PROJECT \
    --member "principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME" \
    --role "ROLE_NAME"

    Ganti kode berikut:

    • GCS_PROJECT: project ID bucket Cloud Storage Anda.
    • PROJECT_NUMBER: nomor project numerik cluster GKE Anda. Untuk menemukan nomor project Anda, lihat Mengidentifikasi project.
    • PROJECT_ID: project ID cluster GKE Anda.
    • NAMESPACE: nama namespace Kubernetes untuk Akun Layanan Kubernetes.
    • KSA_NAME: nama ServiceAccount Kubernetes baru Anda.
    • ROLE_NAME: peran IAM yang akan ditetapkan ke ServiceAccount Kubernetes Anda.
      • Untuk beban kerja hanya baca, gunakan peran Storage Object Viewer (roles/storage.objectViewer).
      • Untuk beban kerja baca-tulis, gunakan peran Storage Object User (roles/storage.objectUser).

Bersiap memasang bucket Cloud Storage FUSE

Bagian ini membahas cara memasang bucket Cloud Storage FUSE di cluster Anda.

Menentukan anotasi Pod

Driver CSI mengandalkan anotasi Pod untuk mengidentifikasi apakah Pod Anda menggunakan volume yang didukung Cloud Storage atau tidak. Jika mendeteksi anotasi yang diperlukan, driver akan memasukkan container sidecar bernama gke-gcsfuse-sidecar ke dalam Pod workload Anda. Instance Cloud Storage FUSE berjalan di dalam container sidecar dan memasang bucket Cloud Storage untuk workload Anda.

Agar driver CSI dapat memasang bucket Cloud Storage, pastikan Anda menentukan anotasi gke-gcsfuse/volumes: "true" dalam spesifikasi Pod, pada kolom metadata. Jika Anda ingin volume yang didukung Cloud Storage digunakan oleh jenis workload Kubernetes lainnya (misalnya Job, Deployment, atau StatefulSet), pastikan Anda mengonfigurasi anotasi pada kolom spec.template.metadata.annotations.

Jika Anda menggunakan Istio atau Cloud Service Mesh, tambahkan anotasi tingkat Pod berikut:

proxy.istio.io/config: '{ "holdApplicationUntilProxyStarts": true }'
traffic.sidecar.istio.io/excludeOutboundIPRanges: 169.254.169.254/32

Mengonfigurasi resource untuk container sidecar

Secara default, penampung sidecar dikonfigurasi dengan permintaan resource berikut, tanpa batas resource yang ditetapkan (untuk cluster Standar):

  • CPU 250m
  • Memori 256 MiB
  • Penyimpanan efemeral 5 GiB

Untuk menimpa nilai ini, Anda dapat menentukan anotasi gke-gcsfuse/[cpu-limit|memory-limit|ephemeral-storage-limit|cpu-request|memory-request|ephemeral-storage-request] seperti yang ditunjukkan dalam contoh berikut:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
    gke-gcsfuse/cpu-limit: "10"
    gke-gcsfuse/memory-limit: 10Gi
    gke-gcsfuse/ephemeral-storage-limit: 1Ti
    gke-gcsfuse/cpu-request: 500m
    gke-gcsfuse/memory-request: 1Gi
    gke-gcsfuse/ephemeral-storage-request: 50Gi

Gunakan pertimbangan berikut saat menentukan jumlah resource yang akan dialokasikan:

  • Jika Anda hanya menetapkan salah satu anotasi permintaan atau batas resource, GKE Autopilot akan menerapkan nilai yang sama untuk permintaan resource dan batas resource.
  • Jika Pod workload Anda menggunakan beberapa volume Cloud Storage, resource container sidecar digunakan bersama oleh beberapa instance Cloud Storage FUSE. Jika ini adalah situasi Anda, pertimbangkan untuk meningkatkan alokasi resource untuk beberapa volume Cloud Storage.
  • Alokasikan lebih banyak CPU ke penampung sidecar jika workload Anda memerlukan throughput yang lebih tinggi. CPU yang tidak memadai akan menyebabkan throttling Cloud Storage FUSE.
  • Jika workload Anda perlu memproses file dalam jumlah besar, dan cache metadata Cloud Storage FUSE diaktifkan, tingkatkan alokasi memori penampung sidecar. Konsumsi memori Cloud Storage FUSE untuk penyimpanan cache metadata sebanding dengan jumlah file, tetapi tidak dengan ukuran file. Memori yang tidak memadai akan menyebabkan error kehabisan memori Cloud Storage FUSE dan membuat aplikasi beban kerja error.
  • Untuk caching file, Cloud Storage FUSE secara default meng-cache file di direktori sementara lokal. Perkirakan kapasitas ruang kosong yang diperlukan workload Anda untuk cache file, dan tingkatkan batas penyimpanan efemeral Anda sesuai kebutuhan tersebut. Untuk mempelajari lebih lanjut, lihat atribut volume.
  • Untuk operasi tulis, Cloud Storage FUSE secara default menyimpan file di direktori sementara lokal sebelum file diupload ke bucket Cloud Storage. Perkirakan kapasitas ruang kosong yang diperlukan workload Anda untuk staging saat menulis file berukuran besar, dan tingkatkan batas penyimpanan efemeral Anda sesuai kebutuhan tersebut. Untuk mempelajari lebih lanjut, lihat Semantik Operasi Baca/Tulis dalam dokumentasi GitHub Cloud Storage FUSE.
  • Anda dapat menggunakan nilai "0" untuk menghapus batas atau permintaan resource di cluster Standar. Misalnya, anotasi gke-gcsfuse/memory-limit: "0" akan mengosongkan batas memori penampung sidecar dengan permintaan memori default. Hal ini berguna jika Anda tidak dapat menentukan jumlah resource yang diperlukan Cloud Storage FUSE untuk workload, dan ingin mengizinkan Cloud Storage FUSE menggunakan semua resource yang tersedia di node. Setelah menghitung persyaratan resource untuk Cloud Storage FUSE berdasarkan metrik beban kerja, Anda dapat menetapkan batas yang sesuai.

Mengonfigurasi image pribadi untuk penampung sidecar

Bagian ini menjelaskan cara menggunakan image penampung sidecar jika Anda menghostingnya di registry penampung pribadi. Skenario ini mungkin berlaku jika Anda perlu menggunakan node pribadi untuk tujuan keamanan. Untuk mengonfigurasi dan menggunakan image penampung sidecar pribadi, ikuti langkah-langkah berikut:

  1. Lihat halaman ini untuk mencari image penampung sidecar publik yang kompatibel.

  2. Ambil ke lingkungan lokal Anda dan kirimkan ke registry container pribadi Anda.

  3. Dalam manifes, tentukan penampung bernama gke-gcsfuse-sidecar hanya dengan kolom image. GKE akan menggunakan image penampung file bantuan yang ditentukan untuk menyiapkan injeksi penampung file bantuan. Berikut ini contohnya:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  containers:
  - name: gke-gcsfuse-sidecar
    image: PRIVATE_REGISTRY/gcs-fuse-csi-driver-sidecar-mounter:PRIVATE_IMAGE_TAG
  - name: main # your main workload container.

Ganti kode berikut:

  • PRIVATE_REGISTRY: registry container pribadi Anda.
  • PRIVATE_IMAGE_TAG: tag image penampung sidecar pribadi Anda.

Mengonfigurasi volume buffering tulis kustom untuk penampung sidecar

Bagian ini menjelaskan cara mengonfigurasi volume buffering kustom untuk buffering tulis Cloud Storage FUSE. Skenario ini mungkin berlaku jika Anda perlu mengganti volume emptyDir default untuk Cloud Storage FUSE guna melakukan staging file dalam operasi tulis. Anda dapat menentukan jenis penyimpanan apa pun yang didukung oleh GKE, seperti PersistentVolumeClaim, dan GKE akan menggunakan volume yang ditentukan untuk buffering operasi tulis file. Hal ini berguna jika Anda perlu menulis file yang lebih besar dari 10 GiB di cluster Autopilot. Untuk menggunakan volume buffering kustom, Anda harus menentukan fsGroup yang bukan nol. Contoh berikut menunjukkan cara menggunakan PVC yang telah ditentukan sebelumnya sebagai volume buffering:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  securityContext:
    fsGroup: FS_GROUP
  containers:
  ...
  volumes:
  - name: gke-gcsfuse-buffer
    persistentVolumeClaim:
      claimName: BUFFER_VOLUME_PVC

Ganti kode berikut:

  • FS_GROUP: ID fsGroup.
  • BUFFER_VOLUME_PVC: nama PVC yang telah ditentukan sebelumnya.

Mengonfigurasi volume cache baca kustom untuk penampung sidecar

Bagian ini menjelaskan cara mengonfigurasi volume cache kustom untuk caching baca Cloud Storage FUSE. Skenario ini mungkin berlaku jika Anda perlu mengganti volume emptyDir default untuk Cloud Storage FUSE guna meng-cache file dalam operasi baca. Anda dapat menentukan jenis penyimpanan apa pun yang didukung oleh GKE, seperti PersistentVolumeClaim, dan GKE akan menggunakan volume yang ditentukan untuk caching file. Hal ini berguna jika Anda perlu meng-cache file yang lebih besar dari 10 GiB di cluster Autopilot. Untuk menggunakan volume cache kustom, Anda harus menentukan fsGroup yang bukan nol. Contoh berikut menunjukkan cara menggunakan PVC yang telah ditentukan sebelumnya sebagai volume cache:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  securityContext:
    fsGroup: FS_GROUP
  containers:
  ...
  volumes:
  - name: gke-gcsfuse-cache
    persistentVolumeClaim:
      claimName: CACHE_VOLUME_PVC

Ganti kode berikut:

  • FS_GROUP: ID fsGroup.
  • CACHE_VOLUME_PVC: nama PVC yang telah ditentukan sebelumnya.

Menyediakan volume sebagai volume efemeral CSI

Volume efemeral CSI yang didukung oleh bucket Cloud Storage terikat dengan siklus proses Pod. Dengan pendekatan penyediaan ini, Anda tidak perlu mempertahankan objek PersistentVolume dan PersistentVolumeClaim yang terkait dengan bucket Cloud Storage setelah Pod dihentikan.

Memakai volume penyimpanan efemeral CSI di Pod

  1. Simpan manifes YAML berikut:

    apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-example-ephemeral
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  terminationGracePeriodSeconds: 60
  containers:
  - image: busybox
    name: busybox
    command: ["sleep"]
    args: ["infinity"]
    volumeMounts:
    - name: gcs-fuse-csi-ephemeral
      mountPath: /data
      readOnly: true
  serviceAccountName: KSA_NAME
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      readOnly: true
      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs"
        gcsfuseLoggingSeverity: warning

    Contoh sebelumnya menunjukkan cara menentukan bucket Cloud Storage secara inline di manifes Pod. Contoh tersebut mencakup kolom berikut:

    • metadata.annotations: anotasi gke-gcsfuse/volumes: "true" harus ada. Lihat Mengonfigurasi resource untuk container sidecar untuk anotasi opsional.
    • spec.terminationGracePeriodSeconds: optional. Secara default, nilai ini ditetapkan ke 30. Jika Anda perlu menulis file berukuran besar ke bucket Cloud Storage, tingkatkan nilai ini untuk memastikan bahwa Cloud Storage FUSE memiliki cukup waktu untuk mengosongkan data setelah aplikasi Anda keluar. Untuk mempelajari lebih lanjut, lihat Praktik terbaik Kubernetes: Mengakhiri dengan masa tenggang.
    • spec.serviceAccountName: menggunakan ServiceAccount Kubernetes yang sama seperti dalam langkah Mengonfigurasi akses ke bucket Cloud Storage menggunakan GKE Workload Identity Federation untuk GKE.
    • spec.volumes[n].csi.driver: gunakan gcsfuse.csi.storage.gke.io sebagai nama driver CSI.
    • spec.volumes[n].csi.volumeAttributes.bucketName: menentukan nama bucket Cloud Storage FUSE Anda. Anda dapat menentukan garis bawah (_) untuk memasang semua bucket yang dapat diakses oleh Akun Layanan Kubernetes. Untuk mempelajari lebih lanjut, lihat Pemasangan Dinamis dalam dokumentasi Cloud Storage FUSE.
    • spec.volumes[n].csi.volumeAttributes.mountOptions: optional. Teruskan opsi pemasangan ke Cloud Storage FUSE. Tentukan flag dalam satu string yang dipisahkan koma, tanpa spasi.
    • spec.volumes[n].csi.volumeAttributes: optional. Teruskan atribut volume lainnya ke Cloud Storage FUSE.
    • spec.volumes[n].csi.readOnly: optional. Tentukan true jika semua volume yang terpasang bersifat hanya baca.
    • spec.containers[n].volumeMounts[m].readOnly: optional. Tentukan true jika hanya volume tertentu yang bersifat hanya baca.

  2. Terapkan manifes ke cluster:

    kubectl apply -f FILE_PATH

    Ganti FILE_PATH dengan jalur ke file YAML.

Memakai volume penyimpanan efemeral CSI di workload Job

  1. Simpan manifes YAML berikut:

    apiVersion: batch/v1
kind: Job
metadata:
  name: gcs-fuse-csi-job-example
  namespace: NAMESPACE
spec:
  template:
    metadata:
      annotations:
        gke-gcsfuse/volumes: "true"
    spec:
      serviceAccountName: KSA_NAME
      containers:
      - name: writer
        image: busybox
        command:
          - "/bin/sh"
          - "-c"
          - touch /data/test && echo $(date) >> /data/test && sleep 10
        volumeMounts:
        - name: gcs-fuse-csi-ephemeral
          mountPath: /data
      - name: reader
        image: busybox
        command:
          - "/bin/sh"
          - "-c"
          - sleep 10 && cat /data/test
        volumeMounts:
        - name: gcs-fuse-csi-ephemeral
          mountPath: /data
          readOnly: true
      volumes:
      - name: gcs-fuse-csi-ephemeral
        csi:
          driver: gcsfuse.csi.storage.gke.io
          volumeAttributes:
            bucketName: BUCKET_NAME
      restartPolicy: Never
  backoffLimit: 1

    Ganti kode berikut:

    Manifes akan men-deploy Job yang memakai bucket Cloud Storage FUSE melalui volume efemeral CSI.

  2. Terapkan manifes ke cluster:

    kubectl apply -f FILE_PATH

    Ganti FILE_PATH dengan jalur ke file YAML.

Jika Anda menggunakan driver CSI dalam workload Job, atau jika Pod RestartPolicy adalah Never, container sidecar akan keluar secara otomatis setelah semua container workload lainnya keluar.

Untuk contoh tambahan, lihat Contoh Aplikasi dalam dokumentasi project GitHub.

Menyediakan volume menggunakan penyediaan statis

Dengan penyediaan statis, Anda dapat membuat satu atau beberapa objek PersistentVolume (PV) yang berisi detail sistem penyimpanan pokoknya. Pod di cluster Anda selanjutnya dapat memakai penyimpanan melalui PersistentVolumeClaims (PVC).

Membuat PersistentVolume

  1. Simpan manifes YAML berikut:

    apiVersion: v1
kind: PersistentVolume
metadata:
  name: gcs-fuse-csi-pv
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  storageClassName: example-storage-class
  mountOptions:
    - implicit-dirs
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME
    volumeAttributes:
      gcsfuseLoggingSeverity: warning
  claimRef:
    name: gcs-fuse-csi-static-pvc
    namespace: NAMESPACE

    Contoh manifes ini menunjukkan cara menentukan PersistentVolume untuk bucket Cloud Storage. Contoh tersebut mencakup kolom berikut:

    • spec.csi.driver: gunakan gcsfuse.csi.storage.gke.io sebagai nama driver CSI.
    • spec.csi.volumeHandle: menentukan nama bucket Cloud Storage Anda. Anda dapat meneruskan garis bawah (_) untuk memasang semua bucket yang dapat diakses oleh Akun Layanan Kubernetes. Untuk mempelajari lebih lanjut, lihat Pemasangan Dinamis dalam dokumentasi Cloud Storage FUSE.
    • spec.mountOptions: optional. Teruskan opsi pemasangan ke Cloud Storage FUSE.
    • spec.csi.volumeAttributes: optional. Teruskan atribut volume ke Cloud Storage FUSE.

  2. Terapkan manifes ke cluster:

    kubectl apply -f FILE_PATH

    Ganti FILE_PATH dengan jalur ke file YAML.

Membuat PersistentVolumeClaim

  1. Simpan manifes YAML berikut:

    apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: gcs-fuse-csi-static-pvc
  namespace: NAMESPACE
spec:
  accessModes:
  - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  storageClassName: example-storage-class

    Contoh manifes ini menunjukkan cara menentukan PersistentVolumeClaim untuk mengikat PersistentVolume. Contoh tersebut mencakup kolom berikut:

    • metadata.namespace: menentukan namespace PersistentVolumeClaim yang harus konsisten dengan namespace workload Anda.

    Untuk mengikat PersistentVolume ke PersistentVolumeClaim, pastikan untuk mengikuti panduan ini:

    • Kolom spec.storageClassName pada manifes PV dan PVC harus cocok. storageClassName tidak perlu merujuk ke objek StorageClass yang ada. Untuk mengikat klaim ini ke sebuah volume, Anda dapat menggunakan sembarang nama yang diinginkan, tetapi nama tersebut tidak boleh kosong.
    • Kolom spec.accessModes pada manifes PV dan PVC harus cocok.
    • spec.capacity.storage pada manifes PersistentVolume harus cocok dengan spec.resources.requests.storage pada manifes PersistentVolumeClaim. Karena bucket Cloud Storage tidak memiliki batas ukuran, Anda dapat menetapkan angka berapa pun untuk kapasitas, tetapi tidak boleh kosong.

  2. Terapkan manifes ke cluster:

    kubectl apply -f FILE_PATH

    Ganti FILE_PATH dengan jalur ke file YAML.

Memakai volume dari PersistentVolumeClaim

  1. Simpan manifes YAML berikut:

    apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-example-static-pvc
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  containers:
  - image: busybox
    name: busybox
    command: ["sleep"]
    args: ["infinity"]
    volumeMounts:
    - name: gcs-fuse-csi-static
      mountPath: /data
      readOnly: true
  serviceAccountName: KSA_NAME
  volumes:
  - name: gcs-fuse-csi-static
    persistentVolumeClaim:
      claimName: gcs-fuse-csi-static-pvc
      readOnly: true

    Contoh ini menunjukkan cara menentukan Pod yang memakai bucket Cloud Storage FUSE melalui PersistentVolumeClaim. Contoh tersebut mencakup kolom berikut:

  2. Terapkan manifes ke cluster:

    kubectl apply -f FILE_PATH

    Ganti FILE_PATH dengan jalur ke file YAML.

Untuk contoh tambahan, lihat Contoh Aplikasi dalam dokumentasi project GitHub.

Menggunakan volume dengan mengaktifkan cache file

Secara default, fitur penyimpanan dalam cache file dinonaktifkan di GKE. Untuk mengaktifkan dan mengontrol penyimpanan dalam cache file, gunakan atribut volume fileCacheCapacity.

GKE menggunakan volume emptyDir untuk caching file Cloud Storage FUSE yang didukung oleh disk booting VM node. Jika Anda mengaktifkan SSD Lokal di node, GKE akan menggunakan SSD Lokal untuk mendukung volume emptyDir.

Anda dapat mengonfigurasi volume cache baca kustom untuk penampung sidecar untuk mengganti volume emptyDir default untuk penyimpanan dalam cache file dalam operasi baca. Untuk keluarga VM CPU dan GPU dengan dukungan SSD Lokal, sebaiknya gunakan penyimpanan SSD Lokal. Untuk keluarga TPU atau Autopilot, sebaiknya gunakan Persistent Disk Seimbang atau Persistent Disk SSD.

Menggunakan volume penyimpanan efemeral CSI dengan mengaktifkan penyimpanan dalam cache file

Untuk men-deploy Pod yang menggunakan bucket Cloud Storage FUSE melalui volume efemeral CSI dengan cache file, ikuti langkah-langkah berikut:

  1. Buat cluster atau node pool dengan penyimpanan efemeral yang didukung SSD Lokal.

    Ikuti dokumentasi GKE untuk membuat cluster atau node pool dengan penyimpanan efemeral yang didukung SSD Lokal.

  2. Simpan manifes YAML berikut:

    apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-file-cache-example
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
    gke-gcsfuse/ephemeral-storage-limit: "50Gi"
spec:
  nodeSelector:
    cloud.google.com/gke-ephemeral-storage-local-ssd: "true"
  restartPolicy: Never
  initContainers:
  - name: data-loader
    image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
    resources:
      limits:
        cpu: 500m
        memory: 1Gi
      requests:
        cpu: 500m
        memory: 1Gi
    command:
      - "/bin/sh"
      - "-c"
      - |
        mkdir -p /test_files
        for i in $(seq 1 1000); do dd if=/dev/zero of=/test_files/file_$i.txt bs=1024 count=64; done
        gcloud storage cp /test_files gs://BUCKET_NAME --recursive
  containers:
  - name: data-validator
    image: busybox
    resources:
      limits:
        cpu: 500m
        memory: 512Mi
      requests:
        cpu: 500m
        memory: 512Mi
    command:
      - "/bin/sh"
      - "-c"
      - |
        echo "first read with cache miss"
        time cat /data/test_files/file_* > /dev/null

        echo "second read from local cache"
        time cat /data/test_files/file_* > /dev/null
    volumeMounts:
    - name: gcs-fuse-csi-ephemeral
      mountPath: /data
  serviceAccountName: KSA_NAME
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs"
        fileCacheCapacity: "10Gi"

    Ganti kode berikut:

    Penampung init data-loader menghasilkan 1.000 file dengan ukuran 64 KiB, dan mengupload file ke bucket Cloud Storage. Penampung utama data-validator membaca semua file dari bucket dua kali, dan mencatat durasi ke dalam log.

  3. Terapkan manifes ke cluster:

    kubectl apply -f FILE_PATH

    Ganti FILE_PATH dengan jalur ke file YAML.

  4. Untuk melihat output log, jalankan perintah berikut:

    kubectl logs -n NAMESPACE gcs-fuse-csi-file-cache-example -c data-validator

    Ganti NAMESPACE dengan namespace beban kerja Anda.

    Outputnya mirip dengan hal berikut ini:

    first read with cache miss
real    0m 54.68s
...
second read from local cache
real    0m 0.38s
...

    Output menunjukkan bahwa pembacaan kedua dengan cache lokal jauh lebih cepat daripada pembacaan pertama dengan cache miss.

Meningkatkan performa pembacaan file besar menggunakan download paralel Cloud Storage FUSE

Anda dapat menggunakan download paralel Cloud Storage FUSE untuk mempercepat pembacaan file besar dari Cloud Storage untuk download multi-thread. Download paralel Cloud Storage FUSE dapat sangat bermanfaat untuk kasus penggunaan penayangan model dengan ukuran baca lebih dari 1 GB.

Contoh umum mencakup:

  • Penyaluran model, tempat Anda memerlukan buffer pengambilan data yang besar untuk mempercepat download model selama booting instance.
  • Pemulihan titik pemeriksaan, tempat Anda memerlukan cache data hanya baca untuk meningkatkan akses satu kali ke beberapa file besar.
Praktik terbaik:

Gunakan download paralel untuk aplikasi yang melakukan pembacaan file besar dengan thread tunggal. Aplikasi dengan paralelisme operasi baca tinggi (menggunakan lebih dari delapan thread) mungkin mengalami performa yang lebih rendah dengan fitur ini.

Untuk menggunakan download paralel dengan driver CSI Cloud Storage FUSE, ikuti langkah-langkah berikut:

  1. Aktifkan cache file. Buat cluster dengan cache file diaktifkan, seperti yang dijelaskan dalam Menggunakan volume penyimpanan efemeral CSI dengan cache file diaktifkan.

  2. Aktifkan download paralel. Dalam manifes, konfigurasikan setelan tambahan ini menggunakan opsi pemasangan:

    1. Tetapkan file-cache:enable-parallel-downloads:true.
    2. Sesuaikan file-cache:parallel-downloads-per-file, file-cache:max-parallel-downloads, dan file-cache:download-chunk-size-mb sesuai kebutuhan.

  3. (Opsional) Atribut volume penyesuaian. Jika diperlukan, pertimbangkan untuk menyesuaikan atribut volume ini:

    • fileCacheForRangeRead untuk pembacaan acak atau sebagian.
    • metadataTypeCacheCapacity dan metadataStatCacheCapacity untuk workload pelatihan.

Klik salah satu tab ini untuk melihat cara mengaktifkan download paralel, bergantung pada apakah Anda menggunakan volume penyimpanan sementara atau penyediaan statis:

Penyimpanan efemeral

apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-example-ephemeral
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  containers:
  ...
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs,file-cache:enable-parallel-downloads:true,file-cache:parallel-downloads-per-file:4,file-cache:max-parallel-downloads:-1,file-cache:download-chunk-size-mb:3"
        fileCacheCapacity: "-1"

Penyediaan statis

apiVersion: v1
kind: PersistentVolume
metadata:
  name: gcs-fuse-csi-pv
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  storageClassName: example-storage-class
  mountOptions:
    - implicit-dirs
    - file-cache:enable-parallel-downloads:true
    - file-cache:parallel-downloads-per-file:4
    - file-cache:max-parallel-downloads:-1
    - file-cache:download-chunk-size-mb:3
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME
    volumeAttributes:
      fileCacheCapacity: "-1"
  claimRef:
    name: gcs-fuse-csi-static-pvc
    namespace: NAMESPACE

Mengonfigurasi cara bucket Cloud Storage FUSE dipasang

Bagian ini menjelaskan cara mengonfigurasi volume Cloud Storage FUSE.

Opsi pemasangan

Driver CSI Cloud Storage FUSE mendukung opsi pemasangan untuk mengonfigurasi cara memasang bucket Cloud Storage di sistem file lokal Anda. Untuk mengetahui daftar lengkap opsi pemasangan yang didukung, lihat dokumentasi CLI gcsfuse.

Anda dapat menentukan flag pemasangan dengan cara berikut:

  • Di kolom spec.mountOptions pada manifes PersistentVolume, jika Anda menggunakan penyediaan statis.
  • Di kolom spec.volumes[n].csi.volumeAttributes.mountOptions, jika Anda menggunakan volume efemeral CSI.

Atribut volume

Driver CSI Cloud Storage FUSE tidak memungkinkan Anda menentukan file konfigurasi Cloud Storage FUSE secara langsung. Anda dapat mengonfigurasi beberapa kolom dalam file konfigurasi menggunakan atribut volume berikut. Nilai diterjemahkan ke kolom file konfigurasi.

  • gcsfuseLoggingSeverity

    • Deskripsi: Tingkat keparahan log yang Anda inginkan untuk dihasilkan oleh Cloud Storage FUSE, yang dinyatakan sebagai enum. Atribut volume ini diterjemahkan ke kolom file konfigurasi logging:severity.

    • Nilai yang valid (diurutkan dari tingkat keparahan terendah hingga tertinggi):

      • trace
      • debug
      • info
      • warning
      • error

    • Nilai default: info.

  • fileCacheCapacity

    • Deskripsi: Ukuran maksimum yang dapat digunakan cache file. Jika nilai yang ditampilkan bukan nol, atribut volume ini akan mengaktifkan penyimpanan dalam cache file di Cloud Storage FUSE. Atribut volume ini diterjemahkan ke kolom file konfigurasi file-cache:max-size-mb.

    • Nilai yang valid:

      • Nilai Quantity, misalnya: 500Mi, 10Gi.
      • "-1": untuk menggunakan seluruh kapasitas yang tersedia di volume cache.
      • "0": cache file dinonaktifkan.

    • Nilai default: "0".

  • fileCacheForRangeRead

    • Deskripsi: Apakah objek lengkap harus didownload secara asinkron dan disimpan di direktori cache Cloud Storage FUSE saat pembacaan pertama dilakukan dari offset non-nol. Nilai ini harus disetel ke "true" jika Anda berencana melakukan beberapa pembacaan acak atau pembacaan sebagian. Atribut volume ini diterjemahkan ke kolom file konfigurasi file-cache:cache-file-for-range-read.

    • Nilai yang valid:

      • Nilai boolean dalam format string: "true", "false".

    • Nilai default: "false".

  • metadataStatCacheCapacity

    • Deskripsi: Ukuran maksimum yang dapat digunakan cache statistik. Cache statistik selalu disimpan sepenuhnya dalam memori. Jika Anda sudah menggunakan opsi pemasangan stat-cache-capacity, nilainya akan tetap dihormati dan akan diterjemahkan dengan tepat ke konfigurasi baru ini. Atribut volume ini diterjemahkan ke kolom file konfigurasi metadata-cache:stat-cache-max-size-mb.

    • Nilai yang valid:

      • Nilai Jumlah, misalnya: 500Mi, 1Gi.
      • "-1": untuk mengizinkan cache statistik menggunakan memori sebanyak yang diperlukan.
      • "0": cache statistik dinonaktifkan.
      • Gunakan nilai default 32Mi jika beban kerja Anda melibatkan hingga 20.000 file. Jika beban kerja Anda lebih besar dari 20.000 file, tingkatkan ukuran sebesar nilai 10 MiB untuk setiap tambahan 6.000 file, rata-rata ~1.500 byte per file.

    • Nilai default: 32Mi.

  • metadataTypeCacheCapacity

    • Deskripsi: Ukuran maksimum per direktori yang dapat digunakan cache jenis. Cache jenis selalu disimpan sepenuhnya di memori. Atribut volume ini diterjemahkan ke kolom file konfigurasi metadata-cache:type-cache-max-size-mb.

    • Nilai yang valid:

      • Nilai Quantity, misalnya: 500Mi, 1Gi.
      • "-1": untuk mengizinkan cache jenis menggunakan memori sebanyak yang diperlukan.
      • "0": cache jenis dinonaktifkan.
      • Gunakan nilai default 4Mi jika jumlah maksimum file dalam satu direktori dari bucket yang Anda pasang berisi 20.000 file atau kurang. Jika jumlah maksimum file dalam satu direktori yang Anda pasang berisi lebih dari 20.000 file, tingkatkan ukurannya sebesar 1 MiB untuk setiap 5.000 file, rata-rata ~200 byte per file.

    • Nilai default: 4Mi.

  • metadataCacheTTLSeconds

    • Deskripsi: Time to live (TTL), dalam detik, dari entri metadata yang di-cache. Jika Anda sudah menggunakan opsi pemasangan stat-cache-ttl atau type-cache-ttl, nilainya akan tetap dihormati dan akan diterjemahkan dengan tepat ke konfigurasi baru ini. Atribut volume ini diterjemahkan ke kolom file konfigurasi metadata-cache:ttl-secs.

    • Nilai yang valid:

      • Nilai bilangan bulat dalam format string, misalnya: "600".
      • "-1": mengabaikan masa berlaku TTL dan menayangkan file dari cache setiap kali tersedia.
      • "0": memastikan file terbaru dibaca. Menggunakan nilai 0 akan mengeluarkan panggilan metadata Get untuk memastikan pembuatan objek untuk file dalam cache cocok dengan yang disimpan di Cloud Storage.

    • Nilai default: "60".

Anda dapat menentukan atribut volume dengan cara berikut:

  • Di kolom spec.csi.volumeAttributes pada manifes PersistentVolume, jika Anda menggunakan penyediaan statis.
  • Di kolom spec.volumes[n].csi.volumeAttributes, jika Anda menggunakan volume efemeral CSI.

Pertimbangan

Gunakan pertimbangan berikut saat mengonfigurasi pemasangan:

  • Flag berikut tidak diizinkan: app-name, temp-dir, foreground, log-file, log-format, key-file, token-url, dan reuse-token-from-url.
  • Cloud Storage FUSE tidak menjadikan direktori implisit terlihat secara default. Agar direktori ini terlihat, Anda dapat mengaktifkan flag pemasangan implicit-dirs. Untuk mempelajari lebih lanjut, lihat File dan Direktori dalam dokumentasi GitHub Cloud Storage FUSE.
  • Jika Anda menggunakan Konteks Keamanan untuk Pod atau container, atau jika image container Anda menggunakan pengguna atau grup non-root, Anda harus menetapkan flag pemasangan uid dan gid. Anda juga perlu menggunakan flag pemasangan file-mode dan dir-mode untuk menetapkan izin sistem file. Perhatikan bahwa Anda tidak dapat menjalankan perintah chmod, chown, atau chgrp terhadap sistem file Cloud Storage FUSE, sehingga flag pemasangan uid, gid, file-mode, dan dir-mode diperlukan untuk memberikan akses ke pengguna atau grup non-root.
  • Jika Anda hanya ingin memasang direktori di bucket, bukan seluruh bucket, teruskan jalur relatif direktori menggunakan flag only-dir=relative/path/to/the/bucket/root.
  • Untuk menyesuaikan perilaku caching Cloud Storage FUSE, konfigurasikan atribut volume. Lihat dokumentasi Caching Cloud Storage FUSE untuk mengetahui detailnya.
  • Jika perlu menentukan jumlah maksimum koneksi TCP yang diizinkan per server, Anda dapat menentukan maksimum ini menggunakan flag max-conns-per-host. Jumlah maksimum koneksi TCP yang Anda tentukan akan berlaku jika --client-protocol ditetapkan ke http1. Nilai defaultnya adalah 0 yang menunjukkan tidak ada batas pada koneksi TCP (dibatasi oleh spesifikasi mesin).
  • Jika perlu mengonfigurasi opsi pemasangan kernel Linux, Anda dapat meneruskan opsi menggunakan flag o. Misalnya, jika Anda tidak ingin mengizinkan eksekusi langsung biner apa pun pada sistem file yang dipasang, tetapkan flag o=noexec. Setiap opsi memerlukan flag terpisah, misalnya, o=noexec,o=noatime. Hanya opsi berikut yang diizinkan: exec, noexec, atime, noatime, sync, async, dan dirsync.
  • Jika Anda perlu memecahkan masalah Cloud Storage FUSE, tetapkan flag log-severity ke TRACE. Kemudian, atribut volume gcsfuseLoggingSeverity akan otomatis ditetapkan ke trace.
  • Driver CSI Cloud Storage FUSE tidak mengizinkan Anda mengubah kolom cache-dir di file konfigurasi Cloud Storage FUSE, gunakan atribut volume fileCacheCapacity untuk mengaktifkan atau menonaktifkan penyimpanan dalam cache file. Untuk mengganti volume emptyDir default untuk penyimpanan dalam cache file, Anda dapat mengonfigurasi volume cache kustom untuk penampung sidecar.

Metrik Cloud Storage FUSE

Metrik Cloud Storage FUSE berikut kini tersedia melalui GKE Monitoring API. Detail tentang metrik Cloud Storage FUSE seperti label, jenis, dan unit dapat ditemukan di Metrik Sistem GKE. Metrik ini tersedia untuk setiap Pod yang menggunakan Cloud Storage FUSE dan memungkinkan Anda mengonfigurasi insight per volume dan bucket.

Metrik sistem file

Metrik sistem file melacak performa dan kondisi sistem file Anda, termasuk jumlah operasi, error, dan kecepatan operasi. Metrik ini dapat membantu mengidentifikasi bottleneck dan mengoptimalkan performa.

  • gcsfusecsi/fs_ops_count
  • gcsfusecsi/fs_ops_error_count
  • gcsfusecsi/fs_ops_latency

Metrik Cloud Storage

Anda dapat memantau metrik Cloud Storage, termasuk volume data, kecepatan, dan aktivitas permintaan, untuk memahami cara aplikasi Anda berinteraksi dengan bucket Cloud Storage. Data ini dapat membantu Anda mengidentifikasi area untuk pengoptimalan, seperti meningkatkan pola baca atau mengurangi jumlah permintaan.

  • gcsfusecsi/gcs_download_bytes_count
  • gcsfusecsi/gcs_read_count
  • gcsfusecsi/gcs_read_bytes_count
  • gcsfusecsi/gcs_reader_count
  • gcsfusecsi/gcs_request_count
  • gcsfusecsi/gcs_request_latencies

Metrik cache file

Anda dapat memantau metrik cache file, termasuk volume pembacaan data, kecepatan, dan rasio hit cache, untuk mengoptimalkan Cloud Storage FUSE dan performa aplikasi. Analisis metrik ini untuk meningkatkan strategi penyimpanan dalam cache dan memaksimalkan hit cache.

  • gcsfusecsi/file_cache_read_bytes_count
  • gcsfusecsi/file_cache_read_latencies
  • gcsfusecsi/file_cache_read_count

Menonaktifkan driver CSI Cloud Storage FUSE

Anda tidak dapat menonaktifkan driver CSI Cloud Storage FUSE pada cluster Autopilot.

Anda dapat menonaktifkan driver CSI Cloud Storage FUSE pada cluster Standard yang ada menggunakan Google Cloud CLI.

gcloud container clusters update CLUSTER_NAME \
    --update-addons GcsFuseCsiDriver=DISABLED

Ganti CLUSTER_NAME dengan nama cluster Anda.

Pemecahan masalah

Untuk memecahkan masalah saat menggunakan driver CSI Cloud Storage FUSE, lihat Panduan Pemecahan Masalah dalam dokumentasi project GitHub.

Langkah berikutnya