Referensi CLI Cloud Storage FUSE

Antarmuka command line (CLI) Cloud Storage FUSE, atau gcsfuse CLI, memungkinkan Anda memasang bucket Cloud Storage sebagai sistem file di komputer lokal. Dokumen ini menjelaskan opsi perintah gcsfuse yang dapat Anda gunakan untuk berinteraksi dengan Cloud Storage FUSE.

Jika Anda menggunakan driver CSI Cloud Storage FUSE untuk memasang bucket ke sistem file lokal di Google Kubernetes Engine, lihat Opsi pemasangan untuk driver CSI Cloud Storage FUSE.

Struktur perintah CLI gcsfuse

Contoh berikut menunjukkan struktur perintah gcsfuse, termasuk perintah yang diperlukan dan opsi gcsfuse opsional.

gcsfuse GLOBAL_OPTIONS BUCKET_NAME MOUNT_POINT

Ganti kode berikut:

  • GLOBAL_OPTIONS adalah opsi gcsfuse yang mengontrol cara pemasangan dan perilaku Cloud Storage FUSE.

  • BUCKET_NAME adalah nama bucket yang akan dipasang. Misalnya, my-mount-bucket. Opsional. Kecualikan nama bucket dari perintah ini untuk menjalankan pemasangan dinamis.

  • MOUNT_POINT adalah direktori lokal tempat bucket akan dipasang. Contoh, /path/to/mount/point.

Opsi gcsfuse CLI

Opsi gcsfuse Deskripsi Nilai yang valid Nilai default
Menonaktifkan autentikasi untuk permintaan. Opsi ini harus ditetapkan jika Anda menggunakan endpoint kustom yang tidak mendukung autentikasi. Opsi ini juga harus ditetapkan jika Anda menggunakan Cloud Storage FUSE dengan bucket publik. Nilai boolean: true, false. false
Nama aplikasi pemasangan. Nilai string, misalnya: my-bucket-mount. ""
Menentukan project yang akan digunakan untuk penagihan saat bucket yang terpasang diakses. Opsi ini sering diperlukan saat memasang bucket yang diaktifkan dengan Requester Pays. Nilai string yang mewakili project ID. ""

Mengaktifkan cache file dan menentukan direktori untuk menyimpan data cache file.

 Jalur, misalnya: /tmp/gcsfuse-cache-path. Nilai kosong menunjukkan bahwa opsi ini dinonaktifkan. Opsi gcsfuse ini dinonaktifkan secara default. ""
Menentukan protokol yang digunakan untuk berkomunikasi dengan backend Cloud Storage.
  • http1 untuk HTTP/1.1
  • http2 untuk HTTP/2
  • grpc untuk gRPC. Untuk menggunakan gRPC dengan Cloud Storage FUSE, sebaiknya gunakan Cloud Storage FUSE versi 2.10.0 atau yang lebih baru.
 http1

Mengekspor metrik ke Cloud Monitoring dengan interval yang ditentukan.

 Bilangan bulat yang mewakili nilai dalam detik, misalnya: 10 (10 detik). 0 menentukan tidak ada ekspor. 0
Menentukan jalur ke file konfigurasi yang ingin Anda gunakan untuk mengonfigurasi perilaku Cloud Storage FUSE. Jalur, misalnya: /etc/gcsfuse.yaml. ""
Menentukan endpoint kustom alternatif untuk mengambil data. Endpoint kustom harus mendukung resource dan operasi yang setara dengan endpoint gRPC Cloud Storage, storage.googleapis.com:443, atau endpoint JSON Cloud Storage, https://storage.googleapis.com/storage/v1. Jika endpoint kustom tidak ditentukan, Cloud Storage FUSE akan menggunakan endpoint JSON Cloud Storage global. Jika autentikasi tidak didukung di endpoint kustom yang Anda tentukan, tetapkan opsi --anonymous-access gcsfuse ke true untuk mengabaikan autentikasi. Endpoint, misalnya: storage.googleapis.com:443. ""
Mengaktifkan output proses debug terkait FUSE. Opsi ini telah diganti dengan opsi --log-severity gcsfuse. Untuk mengaktifkan output proses debug, tetapkan opsi --log-severity gcsfuse ke trace, yang mencakup log rekaman aktivitas, debug, info, peringatan, dan error. Nilai boolean: true, false. false
Mencetak informasi permintaan dan pengaturan waktu Cloud Storage. Opsi gcsfuse ini telah diganti dengan opsi --log-severity gcsfuse. Untuk mengaktifkan output proses debug, tetapkan opsi --log-severity gcsfuse ke trace, yang mencakup log rekaman aktivitas, debug, info, peringatan, dan error. Nilai boolean: true, false. false
Keluar dari program saat pelanggaran invarian internal terdeteksi. Nilai boolean: true, false. false
Mencetak pesan debug saat mutex ditahan terlalu lama. Jika opsi gcsfuse ini ditentukan, tingkat keparahan log akan otomatis ditetapkan ke trace, yang mencakup log rekaman aktivitas, debug, info, peringatan, dan error. Nilai boolean: true, false. false
Bit izin akses untuk direktori, dalam oktal. Nilai string yang mewakili bilangan bulat oktal antara "000" dan "777" (inklusif), misalnya: "755". 755
Menentukan pengambilan data asinkron dari bagian objek Cloud Storage ke dalam buffer dalam memori, sehingga pembacaan berikutnya dapat disajikan dari buffer, bukan memerlukan panggilan jaringan. Nilai boolean: true, false false
Membuat entri cache jenis dengan jenis NonexistentType jika file tidak ditemukan di Cloud Storage. Jika file dibuat di Cloud Storage tetapi entri NonexistentType untuk file tersebut disimpan dalam cache, Cloud Storage FUSE tidak dapat meminta file tersebut hingga entri NonexistentType dihapus dari jenis cache. Nilai boolean: true, false. false
Mengontrol alur jalur tulis sehingga data diupload langsung ke Cloud Storage saat ditulis, bukan melakukan staging penulisan secara lokal dan menguploadnya setelah close() atau fsync(). Untuk mengetahui informasi selengkapnya tentang penulisan streaming, lihat Semantik Cloud Storage FUSE dalam dokumentasi GitHub Cloud Storage FUSE. Nilai boolean: true, false. true

Menentukan ukuran maksimum dalam MiB yang dapat digunakan oleh cache file dan memungkinkan Anda membatasi total kapasitas yang dapat digunakan cache file dalam direktori yang dipasang.
  • Bilangan bulat
  • -1: Menentukan penggunaan seluruh kapasitas cache yang tersedia dalam direktori yang Anda tentukan untuk cache-dir. Ini adalah default hanya jika cache-dir diteruskan.
  • 0: Menonaktifkan cache file.
 -1
Menentukan apakah objek lengkap harus didownload secara asinkron dan disimpan di direktori cache Cloud Storage FUSE saat pembacaan pertama selesai dari offset bukan nol. Opsi gcsfuse ini harus ditetapkan ke true jika Anda berencana melakukan beberapa pembacaan acak atau pembacaan parsial. Nilai boolean: true, false. false
Menentukan ukuran setiap permintaan baca dalam MiB yang dibuat oleh setiap goroutine ke Cloud Storage saat mendownload objek ke dalam cache file. Bilangan bulat 200

Mempercepat pembacaan file besar dengan menggunakan direktori cache file sebagai buffer pengambilan data di awal menggunakan beberapa worker untuk mendownload beberapa bagian file secara paralel.

Download paralel otomatis diaktifkan saat Anda mengaktifkan penyimpanan file dalam cache. Untuk mempelajari lebih lanjut tentang caching file, lihat Caching file di Cloud Storage FUSE.

Untuk mempelajari lebih lanjut download paralel dan cara mengonfigurasi properti pendukung, Download paralel.

 Nilai boolean: true, false. true
Ekspresi reguler yang menentukan file yang akan dikecualikan dari penyimpanan dalam cache. Jika file cocok dengan ekspresi reguler ini, file tersebut tidak akan di-cache, meskipun juga cocok dengan --file-cache-include-regex. Ekspresi reguler dicocokkan dengan jalur file dalam format bucket_name/object_key. Untuk mengetahui informasi selengkapnya, lihat Mengontrol kemampuan cache pada tingkat perincian file menggunakan ekspresi reguler. Nilai string yang mewakili ekspresi reguler. ""
Ekspresi reguler yang menentukan file yang akan disertakan dalam penyimpanan ke dalam cache. Jika opsi ini digunakan, hanya file yang cocok dengan ekspresi reguler ini yang akan di-cache. Ekspresi reguler dicocokkan dengan jalur file dalam format bucket_name/object_key. Untuk mengetahui informasi selengkapnya, lihat Mengontrol kemampuan cache pada tingkat perincian file menggunakan ekspresi reguler. Nilai string yang mewakili ekspresi reguler. ""
Jumlah maksimum goroutine yang dapat dihasilkan pada waktu tertentu di semua tugas download file.
  • Bilangan bulat
  • -1: Menentukan download paralel tanpa batas.
  • 0: Menonaktifkan download paralel. Hanya dapat digunakan jika --enable-parallel-downloads tidak diteruskan atau diteruskan sebagai false.
 Dua kali jumlah core CPU di komputer Anda atau 16, mana saja yang lebih tinggi.
Jumlah permintaan download serentak per file. Bilangan bulat 16
Menentukan bit izin untuk file, dalam oktal. Nilai string yang mewakili bilangan bulat oktal antara "000" dan "777" (inklusif), misalnya: "644". 644
Menjalankan perintah gcsfuse di latar depan. Nilai boolean: true, false. false
Menentukan pemilik ID Grup (GID) dari semua inode.
  • Bilangan bulat yang mewakili GID.
  • -1: GID pemanggil digunakan.
 -1
Menampilkan bantuan tentang Cloud Storage FUSE. Tidak ada Tidak ada
Menampilkan versi Cloud Storage FUSE yang telah diinstal. Tidak ada Tidak ada
Menentukan durasi tunggu klien HTTP Cloud Storage FUSE untuk mendapatkan respons dari server sebelum waktu habis. Durasi, misalnya: 1h10m10s untuk 1 jam, 10 menit, dan 10 detik. 0s menentukan tidak ada waktu tunggu. 0s
Menginstruksikan Cloud Storage FUSE untuk mengabaikan sinyal gangguan sistem, seperti SIGINT yang dipicu oleh Control+C. Hal ini mencegah sinyal menghentikan operasi yang sedang berjalan. Nilai boolean: true, false. true
Secara implisit menyertakan folder dan folder terkelola. Lihat File dan direktori dalam dokumentasi GitHub Cloud Storage FUSE untuk informasi selengkapnya. Nilai boolean: true, false. false

Mengaktifkan cache daftar dan menentukan time to live (TTL) dalam detik untuk entri daftar yang di-cache. Cache daftar disimpan di memori dalam cache halaman, yang dikontrol oleh kernel berdasarkan memori yang tersedia.
  • Bilangan bulat yang mewakili detik, misalnya: 10 (10 detik).
  • 0: Menonaktifkan penyimpanan daftar dalam cache.
  • -1: Mengabaikan masa berlaku entri dan selalu menampilkan respons daftar dari cache jika tersedia.
 0
Menentukan jalur absolut ke file kunci JSON kredensial untuk mengautentikasi permintaan ke Cloud Storage. Secara default, Cloud Storage FUSE menggunakan Kredensial Default Aplikasi untuk mengautentikasi permintaan. Jalur, misalnya: /home/example_user/gcloud-key.json. Jika opsi ini tidak ditetapkan, Kredensial Default Aplikasi akan digunakan.
Menentukan batas bandwidth yang dapat digunakan Cloud Storage FUSE untuk membaca data dari Cloud Storage, yang diukur selama periode 30 detik. Bilangan floating point. -1 menentukan tidak ada batas. -1
Menentukan batas untuk operasi yang dijalankan per detik, yang diukur selama periode 30 detik. Bilangan floating point. -1 menentukan tidak ada batas. -1
Menentukan file untuk menyimpan log yang dapat diurai oleh Fluentd. Jalur, misalnya: /tmp/user-example-bucket-gcsfuse-logs.txt. stdout saat Cloud Storage FUSE dijalankan di latar depan atau syslog saat Cloud Storage FUSE dijalankan di latar belakang
Menentukan format file log.
  • text
  • json
 json
Jumlah maksimum file log yang dirotasi untuk dipertahankan, tidak termasuk file aktif tempat log ditulis.
  • Bilangan bulat
  • 0: Mempertahankan semua file log yang dirotasi
 10
Menentukan apakah file log yang dirotasi dikompresi menggunakan gzip. Nilai boolean: true, false. true
Ukuran maksimum dalam megabyte (MB) yang dapat dicapai file log sebelum dirotasi. Bilangan bulat. Nilai minimum adalah 1. 512

Tingkat keparahan yang Anda inginkan untuk dihasilkan oleh Cloud Storage FUSE. Tingkat keparahan diurutkan dari tingkat keparahan terendah hingga tertinggi. Misalnya, saat Anda menentukan warning, Cloud Storage FUSE akan menghasilkan log peringatan dan error. Secara umum, sebaiknya gunakan tingkat keparahan info.
  • off: menonaktifkan semua logging.
  • error: berisi pesan tentang masalah serius yang mencegah Cloud Storage FUSE menyelesaikan operasi, atau menunjukkan kegagalan seperti kegagalan pemasangan, error izin, dan error input/output (I/O) kritis.
  • warning: berisi pesan yang menunjukkan potensi masalah yang tidak kritis, tetapi dapat menyebabkan masalah jika tidak ditangani. Potensi masalah mencakup masalah koneksi non-fatal, peringatan penghentian penggunaan, pertentangan resource yang dapat menyebabkan sedikit penurunan performa, dan percobaan ulang untuk kegagalan sementara. Tingkat keparahan ini juga mencakup informasi yang diberikan dalam tingkat keparahan error.
  • info: berisi informasi logging umum seperti pesan startup dan shutdown, atau informasi tentang operasi pemasangan yang berhasil, update progres, dan setelan konfigurasi. Tingkat keparahan ini juga mencakup informasi tentang tingkat keparahan warning dan error.
  • debug: berisi informasi logging seperti pesan startup dan shutdown, atau informasi tentang operasi pemasangan yang berhasil, update progres, dan setelan konfigurasi. Tingkat keparahan ini juga mencakup informasi yang diberikan dalam tingkat keparahan info, warning, dan error.
  • trace: berisi detail terperinci tentang setiap operasi dan panggilan fungsi Cloud Storage FUSE, yang menguraikan interaksi gcsfuse dengan driver FUSE kernel dan Cloud Storage. Tingkat keparahan ini juga mencakup detail yang diberikan dalam tingkat keparahan debug, info, warning, dan error.
 info
Menentukan jumlah maksimum koneksi TCP yang diizinkan per server. Hal ini mulai berlaku jika --client-protocol ditetapkan ke http1. Bilangan bulat antara 0 dan 2147483647. 0 menentukan tidak ada batas pada koneksi TCP. 0
Menentukan jumlah maksimum koneksi tidak ada aktivitas yang diizinkan per server. Hal ini mulai berlaku jika --client-protocol ditetapkan ke http1. Bilangan bulat antara 0 dan 2147483647. 0 menentukan tidak ada batas pada koneksi tidak ada aktivitas. 0
Menentukan frekuensi maksimum operasi dicoba ulang jika operasi gagal, sehingga mencegah loop percobaan ulang tanpa akhir.
  • Bilangan bulat yang menunjukkan jumlah maksimum upaya percobaan ulang, misalnya: 10.
  • 0: Memungkinkan upaya percobaan ulang tanpa batas.
 0
Menentukan durasi maksimum Cloud Storage FUSE diizinkan untuk tidur dalam loop percobaan ulang dengan backoff eksponensial. Setelah durasi backoff melebihi durasi maksimum yang ditentukan, percobaan ulang akan dilanjutkan dengan durasi maksimum yang ditentukan. Durasi, misalnya: 1h5m50s (1 jam, 5 menit, dan 50 detik) atau 60s (60 detik). 30s

Menentukan time to live (TTL) dalam detik untuk entri cache stat negatif, yang menyimpan hasil untuk file yang tidak ada dalam cache.
  • Bilangan bulat yang mewakili detik, misalnya: 10 (10 detik).
  • 0: Menonaktifkan caching stat negatif.
  • -1: Mengizinkan caching stat negatif tanpa batas dan menonaktifkan masa berlaku TTL.
 5
Menentukan time to live (TTL) dalam detik untuk entri metadata yang di-cache.
  • Bilangan bulat yang mewakili detik, misalnya: 30 (30 detik).
  • -1: Mengabaikan masa berlaku TTL dan menyajikan file dari cache setiap kali tersedia.
  • 0: Gunakan file terbaru. Penggunaan nilai ini akan mengeluarkan panggilan metadata Get untuk memastikan bahwa pembuatan objek untuk file dalam cache cocok dengan yang disimpan di Cloud Storage.
 60
Menentukan opsi pemasangan tambahan khusus sistem. Sebagian besar opsi pemasangan umum di FUSE seperti suid didukung oleh Cloud Storage FUSE dan dapat diteruskan bersama dengan opsi -o. Opsi pemasangan di FUSE, misalnya:
  • rw: Pasang sebagai baca-tulis.
  • ro: Pasang sebagai hanya baca.
 ""
Hanya memasang direktori tertentu dalam bucket. Jalur, misalnya: /etc/gcsfuse.yaml. ""
Menerapkan serangkaian konfigurasi Cloud Storage FUSE yang telah ditetapkan dan dioptimalkan untuk caching, threading, dan ukuran buffer guna membantu Anda mencapai performa tinggi untuk jenis workload tertentu, seperti pelatihan, inferensi, dan checkpoint. Untuk mempelajari lebih lanjut setiap konfigurasi yang telah ditetapkan berdasarkan jenis workload Anda, lihat Konfigurasi berbasis profil untuk workload AI/ML.
  • String, misalnya, "aiml-checkpointing".
  • "aiml-training": mengoptimalkan performa untuk pembacaan set data besar dengan throughput tinggi dan mencegah hardware GPU Cloud dan Cloud TPU menunggu data.
  • aiml-checkpointing: mengoptimalkan performa untuk penulisan throughput tinggi untuk file besar dengan mengurangi waktu yang diperlukan untuk menyimpan checkpoint multi-gigabyte secara drastis, sehingga meminimalkan jeda pelatihan.
  • aiml-serving: mengoptimalkan performa untuk menyajikan workload dengan menyederhanakan akses data dan menerapkan mekanisme caching.
 ""

Mengekspos endpoint metrik Prometheus pada port dan jalur /metrics yang ditentukan.

 Bilangan bulat yang mewakili port yang ingin Anda tentukan. 0

Menentukan jumlah maksimum blok yang tersedia untuk pembacaan yang di-buffer di semua proses penanganan file.
  • Bilangan bulat
  • 0: menonaktifkan pembacaan yang di-buffer.
  • -1: menetapkan nilai ke blok tanpa batas.
 40
Mengizinkan penggantian nama direktori yang berisi turunan yang lebih sedikit dari batas yang ditentukan. Bilangan bulat antara 0 dan 2147483647. 0
Menentukan pengali untuk backoff eksponensial antara percobaan ulang berturut-turut. Bilangan floating point. 2
Menentukan apakah akan menggunakan kembali token yang diperoleh dari --token-url. Nilai boolean: true, false. true
Menentukan ukuran potongan data yang akan didownload dari Cloud Storage, dalam megabyte (MB). Bilangan bulat antara 1 dan 1024. 200
Menentukan jumlah entri yang dapat disimpan oleh cache statistik. Opsi gcsfuse ini telah diganti dengan opsi --stat-cache-max-size-mb gcsfuse. Bilangan bulat 4096
Ukuran memori maksimum yang dapat digunakan cache stat, dalam MiB. Cache stat selalu disimpan sepenuhnya di memori.
  • Bilangan bulat. Sebaiknya lakukan tindakan berikut:
    • 34 jika workload Anda melibatkan hingga 20.000 file.
    • Jika workload Anda lebih besar dari 20.000 file, tingkatkan ukuran dengan nilai 10 untuk setiap tambahan 6.000 file, dengan cache stat menggunakan rata-rata 1.720 byte per file (termasuk 220 untuk informasi jenis).
  • -1: Tidak menetapkan batas, di mana cache stat menggunakan memori sebanyak yang diperlukan.
  • 0: Menonaktifkan cache stat.
 34
Menentukan durasi penyimpanan atribut StatObject dan atribut inode ke dalam cache. Opsi ini telah diganti dengan opsi --metadata-cache-ttl-secs gcsfuse. Durasi, misalnya: 20s (20 detik). 60s
Menentukan jalur ke direktori sementara tempat penulisan dirilis bertahap untuk pengujian sebelum diupload ke Cloud Storage. Jalur, misalnya: /mnt/ssd/example-user-gcsfuse-temp-dir. /tmp
Menentukan URL untuk mendapatkan token akses jika --key-file tidak ada. URL. ""
Menentukan durasi penyimpanan pemetaan antara nama dan file atau direktori dalam cache di inode direktori, dalam detik. Opsi gcsfuse ini telah diganti dengan opsi --metadata-cache-ttl-secs gcsfuse. Durasi dalam detik, misalnya: 20s (20 detik). 60s
Ukuran maksimum dalam MiB per direktori yang dapat digunakan cache jenis. Cache jenis selalu disimpan sepenuhnya dalam memori.
  • Bilangan bulat. Sebaiknya lakukan tindakan berikut:
    • 4 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 nilainya sebesar 1 untuk setiap 5.000 file, yang merupakan rata-rata sekitar 200 byte per file.
  • -1: Menentukan tidak ada batas dan memungkinkan cache jenis menggunakan memori sebanyak yang diperlukan.
  • 0: Menonaktifkan cache jenis.
 4
Mengaktifkan pengambilan data latar belakang metadata untuk objek dalam direktori selama cache tidak ditemukan. Flag ini melakukan update batch ke cache metadata, sehingga mengurangi latensi secara signifikan untuk pencarian file berikutnya dalam direktori. Nilai boolean: true, false. false
Menentukan entri metadata maksimum yang akan diambil di awal per direktori. Nilai yang menentukan lebih dari 5.000 entri metadata akan menghasilkan beberapa panggilan Objects: list Cloud Storage berurutan, karena setiap panggilan individual dibatasi hingga 5.000 hasil. Bilangan bulat antara -1 dan 2147483647. Tetapkan ke -1 untuk mengambil data semua entri. 5000
Jumlah maksimum worker latar belakang serentak yang diizinkan untuk melakukan pengambilan data metadata di semua direktori. Bilangan bulat antara -1 dan 2147483647. Tetapkan ke -1 untuk worker tanpa batas. 10
Menentukan pemilik ID Pengguna (UID) semua inode.
  • Bilangan bulat yang mewakili UID.
  • -1: UID pemanggil digunakan.
 -1

Menentukan jumlah maksimum potongan data yang tersedia untuk penulisan streaming di semua file. Setiap file menggunakan satu potongan data 32 MiB secara default.
  • Bilangan bulat
  • 0: menonaktifkan penulisan streaming.
  • -1: menetapkan nilai ke potongan tak terbatas.
  • Nilai default untuk perangkat berspesifikasi rendah dengan resource terbatas: 4
  • Nilai default untuk mesin spesifikasi tinggi dengan jumlah resource yang besar: 1600

Kembali ke atas