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 pembacaan aplikasi yang menangani file kecil dari bucket Cloud Storage. Fitur cache file FUSE Cloud Storage 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 performa harga Anda. Anda harus memilih ikut serta untuk mengaktifkan penyimpanan file dalam cache dengan driver CSI Cloud Storage FUSE. Untuk mempelajari lebih lanjut praktik terbaik untuk menyimpan dalam cache, lihat Performa dan praktik terbaik 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 for GKE untuk mengelola autentikasi sekaligus memiliki kontrol terperinci atas cara Pod Anda mengakses objek Cloud Storage.
  • Jika Anda menjalankan pelatihan ML dan melayani workload dengan framework seperti Ray, PyTorch, Spark, dan TensorFlow, portabilitas dan kemudahan yang disediakan oleh driver Cloud Storage FUSE CSI memungkinkan Anda menjalankan workload secara langsung di cluster GKE tanpa perlu mengubah kode tambahan.
  • Anda dapat membaca objek Cloud Storage dengan mengaktifkan cache file untuk meningkatkan performa baca. Untuk mempelajari lebih lanjut manfaat penyimpanan file dalam cache, lihat dokumentasi FUSE Cloud Storage.
  • Anda dapat menggunakan volume Cloud Storage FUSE dalam container init.

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 initialize 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 for GKE, ikuti langkah-langkah berikut. Lihat Mengonfigurasi aplikasi untuk menggunakan Workload Identity Federation for 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 mengaktifkan Workload Identity Federation for GKE.
    • LOCATION: lokasi Compute Engine untuk cluster.

  2. Buat namespace yang akan digunakan untuk ServiceAccount Kubernetes. Anda juga dapat menggunakan namespace default atau namespace yang sudah ada.

    kubectl create namespace NAMESPACE

    Ganti kode berikut:

    • NAMESPACE: nama namespace Kubernetes untuk ServiceAccount Kubernetes.

  3. Membuat ServiceAccount Kubernetes yang akan digunakan aplikasi Anda. Anda juga dapat menggunakan ServiceAccount Kubernetes yang ada di namespace apa pun, termasuk ServiceAccount Kubernetes default.

    kubectl create serviceaccount KSA_NAME \
    --namespace NAMESPACE

    Ganti kode berikut:

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

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

    Anda dapat memberikan peran ke ServiceAccount Kubernetes agar 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 ServiceAccount Kubernetes.
    • KSA_NAME: nama Akun Layanan 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 dapat memberikan peran ke ServiceAccount Kubernetes untuk mengakses semua bucket Cloud Storage dalam 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: ID project 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 ServiceAccount Kubernetes.
    • KSA_NAME: nama Akun Layanan 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.

Mengonfigurasi resource untuk container sidecar

Secara default, container file bantuan dikonfigurasi dengan permintaan resource berikut, dengan batas resource yang tidak disetel:

  • CPU 250m
  • Memori 256 MiB
  • Penyimpanan sementara 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 menyetel salah satu anotasi permintaan resource atau anotasi batas, GKE 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 container file bantuan jika beban kerja Anda memerlukan throughput yang lebih tinggi. CPU yang tidak cukup akan menyebabkan throttling FUSE Cloud Storage.
  • Jika beban kerja Anda perlu memproses file dalam jumlah besar, dan caching metadata Cloud Storage FUSE diaktifkan, tingkatkan alokasi memori container file bantuan. Konsumsi memori Cloud Storage FUSE untuk caching metadata sebanding dengan jumlah file, tetapi tidak dengan ukuran file. Memori yang tidak cukup akan menyebabkan error kehabisan memori Cloud Storage FUSE dan membuat aplikasi beban kerja error.
  • Untuk menyimpan file dalam cache, Cloud Storage FUSE secara default meng-cache file di direktori lokal sementara. Perkirakan jumlah ruang kosong yang diperlukan workload Anda untuk caching file, dan tingkatkan batas penyimpanan efemeral. Untuk mempelajari lebih lanjut, lihat atribut volume.
  • Untuk operasi tulis, Cloud Storage FUSE secara default mengatur 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 artikel Membaca/Menulis semantik dalam dokumentasi GitHub FUSE Cloud Storage.
  • Anda dapat menggunakan nilai "0" untuk membatalkan penetapan batas resource atau permintaan apa pun di cluster Standar. Misalnya, anotasi gke-gcsfuse/memory-limit: "0" membiarkan batas memori container file bantuan kosong dengan permintaan memori default. Hal ini berguna ketika Anda tidak dapat menentukan jumlah resource yang dibutuhkan oleh Cloud Storage FUSE untuk beban kerja Anda, dan ingin membiarkan Cloud Storage FUSE menggunakan semua resource yang tersedia di sebuah node. Setelah menghitung kebutuhan resource untuk Cloud Storage FUSE berdasarkan metrik beban kerja, Anda dapat menetapkan batas yang sesuai.

Mengonfigurasi image pribadi untuk container file bantuan

Bagian ini menjelaskan cara menggunakan image container file bantuan jika Anda menghostingnya di container registry pribadi. Skenario ini mungkin berlaku jika Anda perlu menggunakan cluster pribadi untuk tujuan keamanan, atau jika cluster Anda memiliki akses terbatas ke internet publik. Untuk mengonfigurasi dan menggunakan image container file bantuan pribadi, ikuti langkah-langkah berikut:

  1. Lihat halaman ini untuk mencari gambar container file bantuan publik yang kompatibel.

  2. Pindahkan ke lingkungan lokal Anda dan kirim ke container registry pribadi.

  3. Dalam manifes, tentukan penampung bernama gke-gcsfuse-sidecar yang hanya berisi kolom image. GKE akan menggunakan image container file bantuan yang ditentukan untuk mempersiapkan injeksi container 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: container registry pribadi Anda.
  • PRIVATE_IMAGE_TAG: tag gambar container file bantuan pribadi Anda.

Mengonfigurasi volume buffer tulis kustom untuk container file bantuan

Bagian ini menjelaskan cara mengonfigurasi volume buffer kustom untuk buffering tulis FUSE Cloud Storage. Skenario ini mungkin berlaku jika Anda perlu mengganti volume emptyDir default untuk Cloud Storage FUSE guna melakukan stage 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 penulisan file. Tindakan ini berguna jika Anda perlu menulis file yang lebih besar dari 10 GiB di cluster Autopilot. Untuk menggunakan volume buffer kustom, Anda harus menentukan fsGroup bukan nol. Contoh berikut menunjukkan cara menggunakan PVC yang telah ditentukan sebagai volume buffer:

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 file bantuan

Bagian ini menjelaskan cara mengonfigurasi volume cache kustom untuk cache baca FUSE Cloud Storage. Skenario ini mungkin berlaku jika Anda perlu mengganti volume emptyDir default untuk Cloud Storage FUSE untuk 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 menyimpan file dalam cache. Tindakan ini berguna jika Anda perlu menyimpan file dalam cache dengan ukuran lebih dari 10 GiB di cluster Autopilot. Untuk menggunakan volume cache kustom, Anda harus menentukan fsGroup 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 penghentian Pod.

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: gunakan ServiceAccount Kubernetes yang sama seperti pada langkah Mengonfigurasi akses ke bucket Cloud Storage menggunakan GKE Workload Identity Federation for 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 ServiceAccount 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 Aplikasi Contoh 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
  claimRef:
    namespace: NAMESPACE
    name: gcs-fuse-csi-static-pvc
  mountOptions:
    - implicit-dirs
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME
    volumeAttributes:
      gcsfuseLoggingSeverity: warning

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

    • spec.claimRef.namespace: menentukan namespace PersistentVolumeClaim.
    • spec.claimRef.name: menentukan nama PersistentVolumeClaim.
    • 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 Kubernetes ServiceAccount. 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
  volumeName: gcs-fuse-csi-pv
  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.
    • spec.volumeName: menentukan nama PersistentVolume.

    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 memasukkan 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 Aplikasi Contoh dalam dokumentasi project GitHub.

Gunakan volume Anda dengan penyimpanan file ke cache yang diaktifkan

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

GKE menggunakan volume emptyDir untuk caching file FUSE Cloud Storage yang didukung oleh boot disk 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 container file bantuan guna mengganti volume emptyDir default untuk caching file dalam operasi baca. Untuk kelompok VM CPU dan GPU yang memiliki dukungan SSD Lokal, sebaiknya gunakan penyimpanan SSD Lokal. Untuk kelompok TPU atau Autopilot, sebaiknya gunakan Persistent Disk Seimbang atau Persistent Disk SSD.

Gunakan volume penyimpanan efemeral CSI dengan penyimpanan file ke cache diaktifkan

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

  1. Buat cluster atau kumpulan node 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
        gsutil -m cp -r /test_files gs://BUCKET_NAME
  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:

    Container init data-loader menghasilkan 1.000 file berukuran 64 KiB, dan mengupload file tersebut 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 yang tidak ditemukan.

Mengonfigurasi cara bucket Cloud Storage FUSE dipasang

Bagian ini menjelaskan cara mengonfigurasi volume FUSE Cloud Storage.

Opsi pemasangan

Driver Cloud Storage FUSE CSI mendukung opsi pemasangan untuk mengonfigurasi cara pemasangan 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. Nilainya diterjemahkan ke kolom file konfigurasi.

  • gcsfuseLoggingSeverity

    • Deskripsi: Tingkat keparahan log yang Anda inginkan untuk dihasilkan oleh Cloud Storage FUSE, dinyatakan sebagai enum. Jika Anda sudah menggunakan opsi pemasangan debug_fuse, debug_fs, atau debug_gcs, konfigurasi baru ini akan otomatis ditetapkan ke trace. Atribut volume ini diterjemahkan ke kolom file konfigurasi logging:severity.

    • Nilai valid (diurutkan dari tingkat keseriusan terendah ke tingkat keseriusan tertinggi):

      • trace
      • debug
      • info
      • warning
      • error

    • Nilai default: info.

  • fileCacheCapacity

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

    • Nilai yang valid:

      • Jumlah, misalnya: 500Mi, 10Gi.
      • "-1": untuk menggunakan seluruh kapasitas volume cache yang tersedia.
      • "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 bukan nol. Nilai ini harus ditetapkan 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 di memori. Jika Anda sudah menggunakan opsi pemasangan stat-cache-capacity, nilai ini akan tetap berlaku 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:

      • Jumlah, misalnya: 500Mi, 1Gi.
      • "-1": untuk membiarkan 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 berdasarkan nilai 10 MiB untuk setiap 6.000 file tambahan, rata-rata ~1.500 byte per file.

    • Nilai default: 32Mi.

  • metadataTypeCacheCapacity

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

    • Nilai yang valid:

      • Jumlah, misalnya: 500Mi, 1Gi.
      • "-1": untuk membiarkan jenis cache menggunakan memori sebanyak yang diperlukan.
      • "0": jenis cache 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, atau rata-rata ~200 byte per file.

    • Nilai default: 4Mi.

  • metadataCacheTtlSeconds

    • Deskripsi: Waktu aktif (TTL), dalam detik, entri metadata yang di-cache. Jika Anda sudah menggunakan opsi pemasangan stat-cache-ttl atau type-cache-ttl, nilai tersebut akan tetap berlaku 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 menyimpan file dari cache setiap kali tersedia.
      • "0": memastikan bahwa file terbaru dibaca. Menggunakan nilai 0 mengeluarkan panggilan metadata Get untuk memastikan bahwa 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 menggunakan Konteks Keamanan untuk Pod atau container, atau jika image container menggunakan pengguna atau grup non-root, Anda harus menetapkan flag pemasangan uid dan gid. Anda juga harus menggunakan tanda 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 FUSE Cloud Storage, 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 FUSE Cloud Storage, konfigurasikan atribut volume. Lihat dokumentasi Pembuatan Cache FUSE Cloud Storage untuk mengetahui detailnya.
  • Jika jumlah inti atau thread lebih tinggi dari 100, ubah max-cons-per-host ke nilai ini.
  • 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 di sistem file yang terpasang, tetapkan tanda 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 debug_fuse, debug_fs, dan debug_gcs. Jika salah satu dari tiga opsi tersebut ditentukan, atribut volume gcsfuseLoggingSeverity akan otomatis disetel ke trace.
  • Driver CSI Cloud Storage FUSE tidak mengizinkan Anda mengubah kolom cache-dir di file konfigurasi FUSE Cloud Storage, gunakan atribut volume fileCacheCapacity untuk mengaktifkan atau menonaktifkan penyimpanan file ke cache. Untuk mengganti volume emptyDir default untuk penyimpanan file dalam cache, Anda dapat mengonfigurasi volume cache kustom untuk container file bantuan.

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 selanjutnya