Mengonfigurasi container sidecar driver CSI Cloud Storage FUSE untuk GKE

Dokumen ini menunjukkan cara mengonfigurasi setelan resource untuk container sidecar driver CSI Cloud Storage FUSE di Google Kubernetes Engine (GKE).

Untuk mengoptimalkan performa dan penggunaan resource aplikasi Anda di GKE, konfigurasikan setelan resource tertentu untuk container sidecar driver CSI Cloud Storage FUSE. Dengan menyiapkan resource ini—seperti image pribadi, buffer tulis kustom, dan volume cache baca kustom—Anda dapat memperoleh kontrol yang lebih besar atas cara aplikasi Anda berinteraksi dengan Cloud Storage. Konfigurasi ini dapat menghasilkan akses data yang lebih cepat, waktu pemrosesan yang lebih singkat, dan berpotensi mengurangi konsumsi resource secara keseluruhan di cluster GKE Anda.

Dokumen ini ditujukan untuk developer, administrator, dan arsitek yang mengoptimalkan performa aplikasi. Untuk mempelajari lebih lanjut peran umum dan contoh tugas yang kami referensikan dalam Google Cloud konten, lihat Peran dan tugas pengguna GKE umum.

Sebelum memulai, pahami konsep workload dan penyimpanan berikut:

Cara kerja container sidecar

Driver CSI Cloud Storage FUSE menggunakan container sidecar untuk memasang bucket Cloud Storage agar dapat diakses sebagai sistem file lokal oleh aplikasi Kubernetes. Container sidecar ini, yang bernama gke-gcsfuse-sidecar, berjalan bersama container workload dalam Pod yang sama. Saat driver mendeteksi anotasi gke-gcsfuse/volumes: "true" dalam spesifikasi Pod, driver akan otomatis menyisipkan container sidecar. Pendekatan container sidecar ini membantu memastikan keamanan dan mengelola resource secara efektif.

Container sidecar menangani kompleksitas pemasangan bucket Cloud Storage dan menyediakan akses sistem file ke aplikasi tanpa mengharuskan Anda mengelola runtime Cloud Storage FUSE secara langsung. Anda dapat mengonfigurasi batas resource untuk container sidecar menggunakan anotasi seperti gke-gcsfuse/cpu-limit dan gke-gcsfuse/memory-limit. Model container sidecar juga memastikan bahwa instance Cloud Storage FUSE terikat dengan siklus proses workload, sehingga mencegahnya menggunakan resource secara tidak perlu. Artinya, container sidecar akan otomatis dihentikan saat container workload keluar, terutama dalam workload Tugas atau Pod dengan RestartPolicy dari Never.

Kompatibilitas OSS Istio

Container sidecar driver CSI Cloud Storage FUSE dan Istio dapat berjalan bersamaan dan serentak di Pod Anda. Namun, di GKE versi 1.29 dan yang lebih baru, Anda mungkin mengalami kegagalan autentikasi jika Cloud Storage FUSE mencoba terhubung ke server metadata sebelum proxy Istio siap. Jika mengalami kegagalan autentikasi ini, Anda dapat menyelesaikan masalah ini dengan menambahkan traffic.sidecar.istio.io/excludeOutboundIPRanges: 169.254.169.254/32 ke metadata.annotations dalam spesifikasi Pod. Anotasi ini mengonfigurasi Istio untuk mengecualikan alamat IP server metadata GKE dari pengalihan.

Mengonfigurasi buffer tulis kustom

Cloud Storage FUSE menyimpan penulisan di direktori lokal, lalu mengupload ke Cloud Storage pada operasi close atau fsync.

Bagian ini menjelaskan cara mengonfigurasi volume buffer kustom untuk penulisan buffering 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. Hal ini berguna jika Anda perlu menulis file yang lebih besar dari 10 GiB di cluster Autopilot.

Anda dapat menentukan jenis penyimpanan apa pun yang didukung oleh driver CSI Cloud Storage FUSE untuk caching file, seperti SSD Lokal, penyimpanan berbasis Persistent Disk, dan RAM disk (memori). GKE akan menggunakan volume yang ditentukan untuk buffering penulisan file. Untuk mempelajari opsi ini lebih lanjut, lihat Memilih penyimpanan untuk mendukung cache file Anda.

Untuk menggunakan volume buffer kustom yang didukung oleh Persistent Disk, Anda harus menentukan fsGroup bukan nol di securityContext Pod Anda. Langkah ini memberikan izin baca atau izin tulis yang diperlukan untuk volume ke container sidecar non-root. Setelan ini tidak diperlukan jika PVC Anda memasang bucket Cloud Storage sebagai volume persisten menggunakan driver CSI Cloud Storage FUSE.

Contoh berikut menunjukkan cara menggunakan PersistentVolumeClaim yang telah ditentukan sebelumnya 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

Bagian ini menjelaskan cara mengonfigurasi volume cache kustom untuk penyimpanan cache 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 penyiapan cache file. Hal ini berguna jika Anda perlu menyimpan dalam cache file yang lebih besar dari 10 GiB di cluster Autopilot.

Untuk menggunakan volume cache kustom yang didukung oleh Persistent Disk, Anda harus menentukan fsGroup non-nol di securityContext Pod Anda. Langkah ini memberikan izin baca atau izin tulis yang diperlukan untuk volume ke container sidecar non-root. Setelan ini tidak diperlukan jika PVC Anda memasang bucket Cloud Storage sebagai volume persisten menggunakan driver CSI Cloud Storage FUSE.

Contoh berikut menunjukkan cara menggunakan PersistentVolumeClaim yang telah ditetapkan 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: fsGroup ID.
  • CACHE_VOLUME_PVC: nama PersistentVolumeClaim yang telah ditentukan sebelumnya.

Mengonfigurasi image pribadi untuk container sidecar

Bagian ini menjelaskan cara menggunakan image container sidecar jika Anda menghostingnya di Container Registry pribadi. Skenario ini mungkin berlaku jika Anda perlu menggunakan node pribadi untuk tujuan keamanan.

Untuk mengonfigurasi dan menggunakan image container sidecar pribadi, ikuti langkah-langkah berikut:

  1. Lihat tabel kompatibilitas GKE ini untuk menemukan image container sidecar publik yang kompatibel.
  2. Tarik ke lingkungan lokal Anda dan kirimkan ke registry container pribadi Anda.

  3. Dalam manifes, tentukan container bernama gke-gcsfuse-sidecar dengan hanya kolom image. GKE akan menggunakan image container sidecar yang ditentukan untuk menyiapkan injeksi container sidecar.

    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. Contoh, us-central1-docker.pkg.dev/my-project/my-registry.
    • PRIVATE_IMAGE_TAG: tag image container sidecar pribadi Anda. Contoh, v1.17.1-gke.1.

Mengonfigurasi resource container sidecar

Secara default, container gke-gcsfuse-sidecar dikonfigurasi dengan permintaan dan batas resource berikut untuk cluster Standard dan Autopilot:

Permintaan:

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

Batas (GKE versi 1.29.1-gke.1670000 dan yang lebih baru):

  • CPU tanpa batas
  • memori tak terbatas
  • penyimpanan efemeral tak terbatas

Batas (sebelum GKE versi 1.29.1-gke.1670000):

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

Secara default, container gke-gcsfuse-metadata-prefetch dikonfigurasi dengan permintaan dan batas resource berikut untuk cluster Standard dan Autopilot:

Permintaan:

  • CPU 10m
  • Memori 10 MiB
  • Penyimpanan efemeral 10 MiB

Batas:

  • CPU 50m
  • Memori 250 MiB
  • penyimpanan efemeral tanpa batas

Di cluster Standard dan Autopilot, Anda dapat mengganti nilai default. Cara GKE menangani resource penampung bergantung pada mode operasi cluster Anda:

  • Cluster standar: Jika salah satu permintaan atau batas ditetapkan dan yang lainnya tidak ditetapkan, batas dan permintaan resource Pod akan ditetapkan sama. Jika permintaan dan batas ditetapkan, Pod akan menggunakan permintaan dan batas resource persis seperti yang Anda tentukan. Jika Anda tidak menetapkan nilai apa pun, resource default (yang dijelaskan di atas) akan diterapkan secara langsung.
  • Cluster Autopilot: Jika salah satu permintaan atau batas ditetapkan dan yang lainnya tidak ditetapkan, batas dan permintaan resource Pod akan ditetapkan sama. Lihat Menetapkan batas resource di Autopilot untuk memahami cara penggantian resource, dan nilai resource default yang ditetapkan akan memengaruhi perilaku pod.

Untuk menimpa nilai default untuk container gke-gcsfuse-sidecar, 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:

Untuk menimpa nilai default untuk penampung gke-gcsfuse-metadata-prefetch (mulai dari GKE versi 1.32.3-gke.1717000 dan yang lebih baru), Anda dapat menentukan anotasi gke-gcsfuse/[metadata-prefetch-cpu-limit|metadata-prefetch-memory-limit|metadata-prefetch-ephemeral-storage-limit|metadata-prefetch-cpu-request|metadata-prefetch-memory-request|metadata-prefetch-ephemeral-storage-request] seperti yang ditunjukkan dalam contoh berikut:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"

    # gke-gcsfuse-sidecar overrides
    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

    # gke-gcsfuse-metadata-prefetch overrides
    gke-gcsfuse/metadata-prefetch-cpu-limit: "10"
    gke-gcsfuse/metadata-prefetch-memory-limit: 10Gi
    gke-gcsfuse/metadata-prefetch-ephemeral-storage-limit: 1Ti
    gke-gcsfuse/metadata-prefetch-cpu-request: 500m
    gke-gcsfuse/metadata-prefetch-memory-request: 1Gi
    gke-gcsfuse/metadata-prefetch-ephemeral-storage-request: 50Gi

Anda dapat menggunakan nilai "0" untuk membatalkan setelan batas atau permintaan resource, tetapi perhatikan bahwa container gke-gcsfuse-sidecar sudah tidak memiliki semua batas (cpu-limit, memory-limit, dan ephemeral-storage-limit), dan container gke-gcsfuse-metadata-prefetch sudah tidak memiliki ephemeral-storage-limit, jadi menetapkan batas ini ke "0" pada cluster dengan GKE versi 1.32.3-gke.1717000 atau yang lebih baru, tidak akan berpengaruh.

Misalnya, menyetel gke-gcsfuse/metadata-prefetch-memory-limit: "0", menunjukkan bahwa Anda ingin batas memori container gke-gcsfuse-metadata-prefetch tidak disetel. Hal ini berguna jika Anda tidak dapat memutuskan jumlah resource yang dibutuhkan fitur pengambilan data metadata untuk beban kerja Anda, dan ingin membiarkan pengambilan data metadata menggunakan semua resource yang tersedia di node.

(Opsional) Menganalisis performa menggunakan Cloud Profiler

Anda dapat menggunakan Cloud Profiler untuk mendapatkan visibilitas berkelanjutan dan terperinci ke dalam konsumsi resource aplikasi yang banyak menggunakan penyimpanan. Data terperinci dapat membantu Anda memantau penggunaan CPU dan penggunaan memori secara proaktif di driver CSI Cloud Storage FUSE dan container sidecar-nya. Insight yang Anda peroleh dari data Cloud Profiler dapat membantu Anda mengidentifikasi jalur kode yang tidak efisien, mengoptimalkan alokasi resource, dan memecahkan masalah kompleks seperti kebocoran memori atau peristiwa kehabisan memori (OOM) yang tidak terduga sebelum memengaruhi stabilitas layanan.

Penggunaan Cloud Profiler bersifat opsional dan dirancang untuk administrator yang memerlukan diagnostik performa mendetail. Cloud Profiler diaktifkan secara default untuk driver node. Untuk container sidecar, fitur ini bersifat opsional dan dapat Anda aktifkan secara manual.

Sebelum mengaktifkan Cloud Profiler

Untuk menggunakan Cloud Profiler dengan driver CSI Cloud Storage FUSE, pastikan Anda menggunakan GKE versi 1.36.0-gke.2403000 atau yang lebih baru. Sebelum membuat profil, Anda harus mengaktifkan Cloud Profiler API dan mengonfigurasi izin IAM yang sesuai untuk komponen yang ingin Anda buat profilnya.

Mengaktifkan API

Mengaktifkan Cloud Profiler API

Memberikan izin ke driver node

Untuk mengirim data pembuatan profil ke Cloud Profiler, driver node memerlukan izin IAM. Karena driver node berjalan di jaringan host secara default, driver tersebut melakukan autentikasi menggunakan akun layanan IAM yang terkait dengan node GKE, bukan menggunakan Workload Identity Federation for GKE.

Berikan peran roles/cloudprofiler.agent ke akun layanan node Anda:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role=roles/cloudprofiler.agent \
    --member=serviceAccount:NODE_SERVICE_ACCOUNT

Ganti kode berikut:

  • PROJECT_ID: Google Cloud Project ID Anda.
  • NODE_SERVICE_ACCOUNT: akun layanan IAM yang digunakan oleh node GKE Anda. Biasanya, akun ini adalah akun layanan Compute Engine default, misalnya, PROJECT_NUMBER-compute@, kecuali jika node Anda dikonfigurasi untuk menggunakan akun layanan yang berbeda.

Memberikan izin ke container sidecar

Untuk mengirim data pembuatan profil ke Cloud Profiler, container sidecar dan proses gcsfuse memerlukan izin IAM. Komponen ini melakukan autentikasi menggunakan Workload Identity Federation for GKE, yang menggunakan Akun Layanan Kubernetes (KSA) yang terkait dengan Pod workload Anda.

Berikan peran roles/cloudprofiler.agent ke KSA yang digunakan Pod Anda:

gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/cloudprofiler.agent \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME \
    --condition=None

Ganti kode berikut:

  • PROJECT_ID: Google Cloud Project ID Anda.
  • PROJECT_NUMBER: nomor project Google Cloud Anda.
  • NAMESPACE: nama namespace Kubernetes Anda.
  • KSA_NAME: nama Akun Layanan Kubernetes Anda.

Mengaktifkan Cloud Profiler untuk workload sidecar

Untuk membuat profil untuk pemasang sidecar dan proses gcsfuse yang mendasarinya, tetapkan atribut volume enableCloudProfilerForSidecar ke "true" dalam spesifikasi beban kerja Anda. Mengaktifkan Cloud Profiler untuk container sidecar juga akan otomatis mengaktifkannya untuk proses gcsfuse yang mendasarinya.

Ganti BUCKET_NAME dengan nama bucket Cloud Storage Anda:

volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: BUCKET_NAME
        enableCloudProfilerForSidecar: "true"

Melihat data pembuatan profil

Untuk melihat data pembuatan profil, buka halaman Cloud Profiler di konsol Google Cloud . Gunakan filter Nama layanan sebagai berikut untuk menganalisis komponen yang sedang Anda selidiki:

Komponen Filter nama layanan
Driver Node gcs-fuse-csi-driver
Pemasang Sidecar gke-gcsfuse-sidecar
GCSFuse gcsfuse

Cloud Profiler mengidentifikasi setiap instance menggunakan format POD_NAME_POD_UID. Hal ini memastikan bahwa setiap instance diidentifikasi secara unik meskipun Pod dimulai ulang.

(Opsional) Nonaktifkan pembuatan profil GCSFuse

Secara default, mengaktifkan pembuatan profil untuk container sidecar juga akan membuat profil proses gcsfuse yang mendasarinya. Anda mungkin ingin menonaktifkan pembuatan profil gcsfuse untuk mengurangi overhead resource atau memfokuskan analisis hanya pada performa container sidecar.

Untuk menonaktifkan pembuatan profil gcsfuse sambil tetap mengaktifkan pembuatan profil sidecar, tambahkan enable-cloud-profiler=false ke atribut mountOptions dalam spesifikasi volume Anda.

Ganti BUCKET_NAME dengan nama bucket Cloud Storage Anda:

volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: BUCKET_NAME
        enableCloudProfilerForSidecar: "true"
        mountOptions: "enable-cloud-profiler=false"

Mengonfigurasi panjang respons logging

Secara default, container gke-gcsfuse-sidecar menghasilkan log pada level info dan error. Namun, untuk men-debug atau melakukan analisis yang lebih mendetail, Anda mungkin perlu menyesuaikan detail logging. Bagian ini menguraikan cara meningkatkan atau menurunkan level logging.

Anda dapat menggunakan opsi pemasangan untuk mengonfigurasi panjang respons logging atau menggunakan kemampuan driver CSI untuk menerjemahkan nilai atribut volume ke dalam setelan konfigurasi gcsfuse yang diperlukan.

Dalam manifes Pod target, sertakan konfigurasi berikut:

      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs"
        gcsfuseLoggingSeverity:  LOGGING_SEVERITY

Untuk menggunakan opsi pemasangan, sertakan konfigurasi berikut dalam manifes Pod target:

  mountOptions: "logging:severity:LOGGING_SEVERITY"

Ganti kode berikut:

  • BUCKET_NAME: nama bucket Cloud Storage Anda.
  • LOGGING_SEVERITY: salah satu nilai berikut, berdasarkan kebutuhan Anda:
    • trace
    • debug
    • info
    • warning
    • error

Setelah Pod di-deploy, driver CSI akan memulai gcsfuse dengan level logging yang baru dikonfigurasi.

Anda dapat menggunakan filter berikut untuk memverifikasi apakah tingkat keparahan logging diterapkan:

resource.labels.container_name="gke-gcsfuse-sidecar"
resource.type="k8s_container"
resource.labels.pod_name="POD_NAME"
"severity:"

Memecahkan masalah

Untuk mengetahui informasi selengkapnya tentang pemecahan masalah driver CSI Cloud Storage FUSE, lihat panduan pemecahan masalah dalam dokumentasi project GitHub.

Langkah berikutnya