Mengonfigurasi pemasangan volume Cloud Storage untuk instance

Halaman ini menunjukkan cara memasang bucket Cloud Storage sebagai volume penyimpanan, menggunakan pemasangan volume Cloud Run.

Memasang bucket sebagai volume di Cloud Run akan menampilkan konten bucket sebagai file dalam sistem file container. Setelah memasang bucket sebagai volume, Anda dapat mengakses bucket seolah-olah itu adalah direktori di sistem file lokal, menggunakan operasi dan library sistem file bahasa pemrograman Anda, bukan menggunakan Library Klien Google API.

Anda dapat memasang volume sebagai hanya baca dan Anda juga dapat menentukan opsi pemasangan untuk volume Anda.

Persyaratan memori

Pemasangan volume Cloud Storage menggunakan memori container Cloud Run untuk aktivitas berikut:

  • Untuk semua caching Cloud Storage FUSE, Cloud Run menggunakan setelan cache stat dengan Time-to-live (TTL) selama 60 detik secara default. Ukuran maksimum default cache stat adalah 32 MB, ukuran maksimum default cache jenis adalah 4 MiB.

  • Saat membaca dari Cloud Storage, Cloud Storage FUSE melakukan panggilan API untuk membaca objek secara langsung, tanpa mendownload seluruh file ke direktori lokal. Cloud Storage FUSE membuat koneksi TCP, dan membaca kembali seluruh objek Cloud Storage, atau hanya bagian file yang Anda tentukan dalam aplikasi atau sistem operasi melalui offset. Saat membaca, Cloud Storage FUSE juga menggunakan memori selain cache statistik dan jenis, seperti array 1 MiB untuk setiap file yang dibaca, dan untuk goroutines.

  • Saat menulis ke Cloud Storage, Cloud Storage FUSE mendukung streaming-writes, yaitu jalur tulis, secara default. Cloud Storage FUSE mengupload data langsung ke Cloud Storage tanpa melakukan staging file sepenuhnya. Setiap file yang Anda buka untuk penulisan streaming menggunakan sekitar 64 MiB memori selama proses upload. Hal ini mengurangi latensi dan penggunaan kapasitas disk, sehingga sangat bermanfaat untuk penulisan berurutan yang besar.

Batasan

Karena Cloud Run menggunakan Cloud Storage FUSE untuk pemasangan volume ini, ada beberapa hal yang perlu diperhatikan saat memasang bucket Cloud Storage sebagai volume:

  • Cloud Storage FUSE tidak menyediakan kontrol konkurensi untuk beberapa penulisan (penguncian file) ke file yang sama. Jika beberapa operasi tulis mencoba mengganti sebuah file, operasi tulis terakhir yang menang dan semua operasi tulis sebelumnya akan hilang.
  • Cloud Storage FUSE bukanlah sistem file yang sepenuhnya sesuai dengan POSIX. Untuk mengetahui detail selengkapnya, lihat dokumentasi Cloud Storage FUSE.

Jalur yang tidak diizinkan

Cloud Run tidak mengizinkan Anda memasang volume di /dev, /proc, atau /sys, atau di subdirektorinya.

Sebelum memulai

Anda memerlukan bucket Cloud Storage untuk dipasang sebagai volume.

Untuk performa baca/tulis yang optimal ke Cloud Storage, lihat Mengoptimalkan performa bandwidth jaringan Cloud Storage FUSE.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk mengonfigurasi pemasangan volume Cloud Storage, minta administrator untuk memberi Anda peran IAM berikut:

Untuk mendapatkan izin yang diperlukan identitas layanan Anda untuk mengakses file dan bucket Cloud Storage, minta administrator Anda untuk memberikan peran Storage Object Viewer (roles/storage.objectViewer) kepada identitas layanan. Jika identitas layanan juga perlu melakukan operasi tulis di bucket, berikan peran Storage Object User (roles/storage.objectUser).

Untuk mengetahui detail selengkapnya tentang peran dan izin Cloud Storage, lihat IAM untuk Cloud Storage.

Untuk mengetahui daftar peran dan izin IAM yang terkait dengan Cloud Run, lihat Peran IAM Cloud Run dan Izin IAM Cloud Run. Jika instance Cloud Run Anda berinteraksi dengan Google Cloud API, seperti Library Klien Cloud, lihat panduan konfigurasi identitas layanan. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat izin deployment dan mengelola akses.

Memasang volume Cloud Storage

Anda dapat mengonfigurasi volume Cloud Storage untuk instance Cloud Run menggunakan Google Cloud CLI, YAML, atau Terraform:

gcloud

Untuk menambahkan pemasangan volume:

gcloud beta run instances update INSTANCE \
--add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,readonly=READ_ONLY

Ganti kode berikut:

  • INSTANCE: nama instance Anda.
  • MOUNT_PATH: jalur relatif tempat Anda memasang volume—misalnya, /mnt/my-volume.
  • BUCKET_NAME: nama bucket Cloud Storage Anda.
  • READ_ONLY: true untuk membuat volume hanya baca, atau false untuk mengizinkan penulisan.

YAML

  1. Jika Anda membuat instance baru, lewati langkah ini. Jika Anda mengupdate instance yang ada, download konfigurasi YAML-nya:

    gcloud beta run instances describe INSTANCE --format export > instance.yaml
  2. Contoh berikut berisi konfigurasi YAML:

    apiVersion: run.googleapis.com/v1
    kind: Instance
    metadata:
      name: INSTANCE
      annotations:
        run.googleapis.com/launch-stage: BETA
    spec:
      containers:
      - image: IMAGE_URL
        volumeMounts:
        - name: VOLUME_NAME
          mountPath: MOUNT_PATH
      volumes:
      - name: VOLUME_NAME
        csi:
          driver: gcsfuse.run.googleapis.com
          readOnly: IS_READ_ONLY
          volumeAttributes:
            bucketName: BUCKET_NAME

    Ganti kode berikut:

    • INSTANCE: nama instance Cloud Run Anda.
    • IMAGE_URL: referensi ke image container, seperti us-docker.pkg.dev/cloudrun/container/hello:latest.
    • VOLUME_NAME: nama apa pun yang Anda inginkan untuk volume Anda. Nilai VOLUME_NAME digunakan untuk memetakan volume ke pemasangan volume.
    • MOUNT_PATH: jalur relatif tempat Anda memasang volume—misalnya, /mnt/my-volume.
    • IS_READ_ONLY: True untuk membuat volume hanya baca, atau False untuk mengizinkan penulisan.
    • BUCKET_NAME: nama bucket Cloud Storage.
  3. Buat atau perbarui instance menggunakan perintah berikut:

    gcloud beta run instances replace instance.yaml

Terraform

Untuk mempelajari cara menerapkan atau menghapus konfigurasi Terraform, lihat Perintah dasar Terraform.

resource "google_cloud_run_v2_instance" "default" {
  provider = google-beta
  name     = "INSTANCE"
  location = "REGION"
  launch_stage = "BETA"

  containers {
    image = "IMAGE_URL"
    volume_mounts {
      name       = "VOLUME_NAME"
      mount_path = "MOUNT_PATH"
    }
  }

  volumes {
    name = "VOLUME_NAME"
    gcs {
      bucket    = google_storage_bucket.default.name
      read_only = IS_READ_ONLY
    }
  }
}

resource "google_storage_bucket" "default" {
  name     = "BUCKET_NAME"
  location = "REGION"
}

Ganti kode berikut:

  • INSTANCE: nama instance Anda.
  • REGION: region Google Cloud , seperti us-west1.
  • IMAGE_URL: referensi ke image container, seperti us-docker.pkg.dev/cloudrun/container/hello:latest.
  • VOLUME_NAME: nama apa pun yang Anda inginkan untuk volume Anda. Nilai VOLUME_NAME digunakan untuk memetakan volume ke pemasangan volume.
  • MOUNT_PATH: jalur relatif tempat Anda memasang volume—misalnya, /mnt/my-volume.
  • IS_READ_ONLY: true untuk membuat volume hanya baca, atau false untuk mengizinkan penulisan.
  • BUCKET_NAME: nama bucket Cloud Storage.

Membaca dan menulis ke volume

Jika menggunakan fitur pemasangan volume Cloud Run, Anda dapat mengakses volume yang terpasang menggunakan library yang sama dalam bahasa pemrograman yang Anda gunakan untuk membaca dan menulis file di sistem file lokal.

Hal ini sangat berguna jika Anda menggunakan container yang sudah ada yang mengharapkan data disimpan di sistem file lokal dan menggunakan operasi sistem file reguler untuk mengaksesnya.

Cuplikan berikut mengasumsikan pemasangan volume dengan mountPath yang ditetapkan ke /mnt/my-volume.

Nodejs

Gunakan modul sistem file untuk membuat file baru atau menambahkan ke file yang ada dalam volume, /mnt/my-volume:

var fs = require('fs');
fs.appendFileSync('/mnt/my-volume/sample-logfile.txt', 'Hello logs!', { flag: 'a+' });

Python

Tulis ke file yang disimpan dalam volume, /mnt/my-volume:

f = open("/mnt/my-volume/sample-logfile.txt", "a")

Go

Gunakan paket os untuk membuat file baru yang disimpan di volume, /mnt/my-volume:

f, err := os.Create("/mnt/my-volume/sample-logfile.txt")

Java

Gunakan class Java.io.File untuk membuat file log di volume, /mnt/my-volume:

import java.io.File;
File f = new File("/mnt/my-volume/sample-logfile.txt");

Konfigurasi volume menggunakan opsi pemasangan

Anda dapat menggunakan opsi pemasangan untuk mengonfigurasi berbagai properti pemasangan volume. Opsi pemasangan yang tersedia memungkinkan Anda mengonfigurasi setelan cache, memasang direktori tertentu, mengaktifkan logging debug, dan perilaku lainnya.

Menentukan opsi pemasangan

Anda dapat menentukan opsi pemasangan menggunakan Google Cloud CLI atau YAML. Opsi pemasangan dipisahkan oleh titik koma (;) di Google Cloud CLI dan dipisahkan oleh koma di YAML, seperti yang ditunjukkan pada tab berikut:

Opsi pemasangan yang umum digunakan

Opsi pemasangan umum digunakan untuk:

  • Mengonfigurasi setelan cache
  • Memasang hanya direktori tertentu dari bucket Cloud Storage
  • Mengonfigurasi kepemilikan volume (uid, gid)
  • Menonaktifkan direktori implisit
  • Menentukan tingkat logging debug.

Mengonfigurasi setelan caching

Anda dapat mengubah setelan caching untuk volume dengan menetapkan opsi pemasangan terkait caching. Tabel berikut mencantumkan setelan, beserta nilai default Cloud Run:

Setelan cache Deskripsi Default
cache-dir Nama volume dalam memori yang akan digunakan sebagai direktori dasar untuk mempertahankan file dari bucket Cloud Storage Anda dalam format cr-volume:{volume name}. Misalnya, jika Anda memiliki volume dalam memori bernama in-memory-1 yang ingin digunakan sebagai direktori cache, tentukan cr-volume:in-memory-1. Untuk mengetahui petunjuk cara menyiapkan volume dalam memori, lihat Mengonfigurasi pemasangan volume dalam memori untuk layanan. Saat Anda mengaktifkan fitur ini, Cloud Run akan mengubah akuntansi resource proses Cloud Storage FUSE dan memperhitungkannya dalam batas memori container. Untuk meningkatkan batas memori container, lihat Mengonfigurasi batas memori untuk layanan.
file-cache-download-chunk-size-mb Menentukan ukuran setiap permintaan baca dalam MiB yang dibuat setiap goroutine ke Cloud Storage saat mendownload objek ke dalam cache file. 200
file-cache-enable-parallel-downloads 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. true
file-cache-max-parallel-downloads Jumlah maksimum goroutine yang dapat dibuat pada waktu tertentu di semua tugas download file. Dua kali jumlah core CPU di komputer Anda atau 16, mana saja yang lebih tinggi.
file-cache-parallel-downloads-per-file Jumlah permintaan download serentak per file. 16
file-cache-cache-file-for-range-read Menentukan apakah objek lengkap harus didownload secara asinkron dan disimpan di direktori cache Cloud Storage FUSE saat pembacaan pertama selesai dari offset bukan nol. false
enable-buffered-read Mengaktifkan buffering baca untuk mengambil data objek terlebih dahulu. Direkomendasikan untuk workload yang membaca file besar secara berurutan (seperti model machine learning atau set data) guna meningkatkan throughput baca secara signifikan dan mengurangi latensi startup container. false
stat-cache-max-size-mb Ukuran maksimum dalam mebibyte (MiB) yang dapat digunakan oleh cache statistik. Cache stat selalu disimpan sepenuhnya dalam memori, sehingga memengaruhi konsumsi memori. Tentukan nilai 32 jika workload Anda melibatkan hingga 20.000 file. Jika workload Anda menggunakan lebih dari 20.000 file, tingkatkan ukuran sebesar nilai 10 untuk setiap tambahan 6.000 file, dengan cache stat menggunakan rata-rata 1.500 byte per file.

Untuk mengizinkan cache stat menggunakan memori sebanyak yang diperlukan, tentukan nilai -1. Untuk menonaktifkan cache stat, tentukan nilai 0.
32
type-cache-max-size-mb Ukuran maksimum dalam MiB per direktori yang dapat digunakan cache jenis. Cache jenis selalu disimpan sepenuhnya dalam memori, sehingga memengaruhi konsumsi memori.

Tentukan nilai 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 rata-rata sekitar 200 byte per file.

Untuk mengizinkan cache jenis menggunakan memori sebanyak yang diperlukan, tentukan nilai -1.

Untuk menonaktifkan cache jenis, tentukan nilai 0.
4

Perintah Google Cloud CLI berikut menetapkan metadata-cache-ttl-secs ke 120 detik dan meningkatkan kapasitas cache stat dan jenis masing-masing menjadi 52 dan 7 MiB:

Mengaktifkan logging debug

Secara default, Cloud Storage FUSE mencatat peristiwa yang memiliki tingkat keparahan Info atau lebih tinggi. Anda dapat mengubah setelan logging menggunakan salah satu tingkat keparahan log berikut, yang tercantum dalam urutan dari yang terendah hingga tertinggi:

  • trace
  • debug
  • info
  • warning
  • error
  • Untuk menonaktifkan semua logging, tentukan nilai off.

Saat Anda menentukan tingkat keparahan, Cloud Storage FUSE akan menghasilkan log untuk peristiwa yang memiliki tingkat keparahan yang sama dengan atau lebih tinggi dari tingkat keparahan yang ditentukan. Misalnya, saat Anda menentukan level warning, Cloud Storage FUSE akan menghasilkan log peringatan dan error.

Menetapkan tingkat keparahan log ke level yang lebih tinggi dari info dapat memengaruhi performa dan menghasilkan data logging dalam jumlah besar, jadi sebaiknya lakukan ini hanya jika diperlukan. Untuk kompatibilitas dengan cloud logging, format log adalah format text, dan format json tidak didukung.

Command line berikut mengaktifkan logging debug:

gcloud beta run instances update INSTANCE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="log-severity=debug"

Ganti kode berikut:

  • INSTANCE: nama instance Anda.
  • MOUNT_PATH: jalur relatif tempat Anda memasang volume—misalnya, /cache.
  • BUCKET_NAME: nama bucket Cloud Storage Anda.

Menonaktifkan direktori implisit

Agar Cloud Storage terlihat lebih seperti sistem file standar, Cloud Run mengaktifkan direktori implisit secara default saat memasang bucket Cloud Storage. Anda dapat menonaktifkan direktori implisit menggunakan opsi pemasangan implicit-dirs. Menonaktifkan direktori implisit dapat meningkatkan performa dan biaya, tetapi memiliki konsekuensi kompatibilitas.

Fitur direktori implisit memungkinkan Cloud Run mengenali file Cloud Storage yang sudah ada dan nama filenya meniru struktur direktori, seperti /mydir/myfile.txt. Jika Anda menonaktifkan direktori implisit, Cloud Run tidak akan dapat mencantumkan atau membaca file tersebut.

Menonaktifkan direktori implisit akan mengurangi jumlah permintaan ke Cloud Storage, yang dapat meningkatkan performa dan biaya aplikasi Anda. Baca dokumentasi File dan direktori Cloud Storage FUSE untuk mempelajari lebih lanjut.

Command line berikut menonaktifkan direktori implisit:

gcloud beta run instances update INSTANCE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="implicit-dirs=false"

Ganti kode berikut:

  • INSTANCE: nama instance Anda.
  • MOUNT_PATH: jalur relatif tempat Anda memasang volume—misalnya, /cache.
  • BUCKET_NAME: nama bucket Cloud Storage Anda.

Memasang direktori tertentu di dalam bucket Cloud Storage Anda

Secara default, Cloud Run memasang seluruh bucket Cloud Storage, yang memberi instance Cloud Run akses ke semua kontennya. Dalam beberapa kasus, Anda mungkin hanya ingin memasang direktori tertentu. Misalnya, jika bucket berisi banyak file, memasang direktori tertentu dapat meningkatkan performa.

Anda juga dapat menerapkannya untuk tujuan isolasi, yaitu saat Anda memerlukan instance yang berbeda untuk memiliki akses ke direktori yang berbeda di bucket penyimpanan.

Command line berikut menentukan direktori yang akan dipasang:

gcloud beta run instances update INSTANCE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="only-dir=images"

Ganti kode berikut:

  • INSTANCE: nama instance Anda.
  • MOUNT_PATH: jalur relatif tempat Anda memasang volume—misalnya, /cache.
  • BUCKET_NAME: nama bucket Cloud Storage Anda.

Setel volume UID dan GID

Gunakan opsi pemasangan uid dan gid untuk mengubah ID Pengguna dan ID Grup untuk volume. Hal ini berguna jika Anda ingin menetapkan kepemilikan file ke pengguna atau grup tertentu yang cocok dengan identitas satu atau beberapa container yang sedang berjalan. Secara default, volume dimiliki oleh root.

Command line berikut menetapkan uid dan gid:

gcloud beta run instances update INSTANCE \
    --add-volume mount-path=MOUNT_PATH,type=cloud-storage,bucket=BUCKET_NAME,mount-options="uid=UID;gid=GID"

Ganti kode berikut:

  • INSTANCE: nama instance Anda.
  • MOUNT_PATH: jalur relatif tempat Anda memasang volume—misalnya, /cache.
  • BUCKET_NAME: nama bucket Cloud Storage Anda.
  • UID: ID pengguna untuk memasang volume.
  • GID: ID grup untuk memasang volume.

Menetapkan opsi pemasangan lainnya

Berikut adalah daftar lengkap semua opsi pemasangan yang didukung oleh Cloud Run.

Direktori

  • implicit-dirs
  • only-dir
  • rename-dir-limit

Debug

  • debug_fuse_errors
  • debug_fuse
  • debug_gcs
  • debug-invariants
  • debug_mutex

Cache

  • stat-cache-capacity
  • stat-cache-ttl
  • type-cache-ttl
  • enable-nonexistent-type-cache

Izin

  • uid
  • gid
  • file-mode
  • dir-mode

Lainnya

  • billing-project
  • client-protocol
  • enable-buffered-read
  • experimental-enable-json-read
  • experimental-opentelemetry-collector-address
  • http-client-timeout
  • limit-bytes-per-sec
  • limit-ops-per-sec
  • max-conns-per-host
  • max-idle-conns-per-host
  • max-retry-sleep
  • -o
  • retry-multiplier
  • sequential-read-size-mb
  • stackdriver-export-interval

Untuk deskripsi mendetail tentang opsi ini, lihat Opsi pemasangan command line Cloud Storage FUSE. Halaman Cloud Storage FUSE mencantumkan semua opsi FUSE yang tersedia, beberapa di antaranya tidak didukung oleh Cloud Run.

Mengoptimalkan performa bandwidth jaringan Cloud Storage FUSE

Untuk performa baca dan tulis yang lebih baik, hubungkan instance Cloud Run Anda ke jaringan VPC menggunakan Direct VPC dan rutekan semua traffic keluar melalui jaringan VPC Anda. Anda dapat melakukannya menggunakan salah satu opsi berikut:

Waktu startup container dan pemasangan Cloud Storage FUSE

Menggunakan Cloud Storage FUSE dapat sedikit meningkatkan waktu cold start container Cloud Run Anda karena Cloud Run memulai pemasangan volume sebelum memulai container. Container Anda hanya akan dimulai jika Cloud Storage FUSE berhasil dipasang.

Perhatikan bahwa Cloud Storage FUSE berhasil memasang volume hanya setelah membuat koneksi ke Cloud Storage. Setiap keterlambatan jaringan dapat berdampak pada waktu startup container. Sejalan dengan itu, jika upaya koneksi gagal, Cloud Storage FUSE akan gagal dipasang dan instance Cloud Run akan gagal dimulai. Selain itu, jika Cloud Storage FUSE memerlukan waktu lebih dari 30 detik untuk melakukan pemasangan, instance Cloud Run akan gagal dimulai karena Cloud Run memiliki total waktu tunggu 30 detik untuk melakukan semua pemasangan.

Karakteristik performa Cloud Storage FUSE

Jika Anda menentukan dua volume, yang masing-masing mengarah ke bucket yang berbeda, dua proses Cloud Storage FUSE akan dimulai. Pemasangan dan proses terjadi secara paralel.

Operasi yang menggunakan Cloud Storage FUSE dipengaruhi oleh bandwidth jaringan karena Cloud Storage FUSE berkomunikasi dengan Cloud Storage menggunakan Cloud Storage API. Beberapa operasi seperti mencantumkan konten bucket dapat berjalan lambat jika bandwidth jaringan rendah. Demikian pula, membaca file besar dapat memerlukan waktu karena hal ini juga dibatasi oleh bandwidth jaringan.

Saat Anda menulis ke bucket, Cloud Storage FUSE akan sepenuhnya menempatkan objek di memori. Artinya, penulisan file besar dibatasi oleh jumlah memori yang tersedia untuk instance container (batas memori container maksimum adalah 32 GiB).

Penulisan akan di-flush ke bucket hanya saat Anda melakukan close atau fsync: objek lengkap kemudian diupload ke bucket. Satu-satunya pengecualian untuk objek yang diupload ulang sepenuhnya ke bucket adalah dalam kasus file dengan konten yang ditambahkan saat file berukuran 2 MiB atau lebih.

Untuk informasi selengkapnya, lihat referensi berikut:

Menghapus dan membuang volume dan pemasangan volume

Anda dapat menghapus semua volume dan pemasangan atau Anda dapat menghapus volume dan pemasangan volume satu per satu.

Menghapus semua volume dan pemasangan volume

Untuk menghapus semua volume dan pemasangan volume dari instance container tunggal, jalankan perintah berikut:

gcloud beta run instances update INSTANCE \
    --clear-volumes \
    --clear-volume-mounts

Menghapus setiap volume dan pemasangan volume

Untuk menghapus volume, Anda juga harus menghapus semua pemasangan volume yang menggunakan volume tersebut.

Untuk menghapus setiap volume atau pemasangan volume, gunakan flag remove-volume dan remove-volume-mount:

gcloud beta run instances update INSTANCE \
    --remove-volume VOLUME_NAME \
    --container=container1 \
    --remove-volume-mount MOUNT_PATH \
    --container=container2 \
    --remove-volume-mount MOUNT_PATH