Halaman ini membahas penyimpanan cache jarak jauh, menyiapkan server untuk menghosting cache, dan menjalankan build menggunakan cache jarak jauh.
Cache jarak jauh digunakan oleh tim developer dan/atau continuous integration (CI) untuk berbagi output build. Jika build Anda dapat direproduksi, output dari satu komputer dapat digunakan kembali dengan aman di komputer lain, yang dapat membuat build menjadi jauh lebih cepat.
Ringkasan
Bazel memecah build menjadi langkah-langkah terpisah, yang disebut tindakan. Setiap tindakan memiliki input, nama {i>output<i}, baris perintah, dan variabel lingkungan. Wajib diisi input dan output yang diharapkan dideklarasikan secara eksplisit untuk setiap tindakan.
Anda dapat menyiapkan server agar menjadi cache jarak jauh untuk output build, yang merupakan output tindakan. {i>Output<i} ini terdiri dari sebuah daftar nama file {i>output<i} dan {i>hash <i}dari kontennya. Dengan cache jarak jauh, Anda dapat menggunakan kembali output build dari build pengguna lain daripada membangun setiap output baru secara lokal.
Untuk menggunakan penyimpanan cache jarak jauh:
- Menyiapkan server sebagai backend cache
- Mengonfigurasi build Bazel untuk menggunakan cache jarak jauh
- Gunakan Bazel versi 0.10.0 atau yang lebih baru
Cache jarak jauh menyimpan dua jenis data:
- Cache tindakan, yang merupakan peta hash tindakan ke metadata hasil tindakan.
- Penyimpanan alamat konten (CAS) dari file output.
Perhatikan bahwa cache jarak jauh juga menyimpan {i>stdout<i} dan {i>stderr<i} untuk setiap tindakan. Memeriksa {i>stdout/stderr<i} Bazel bukanlah sinyal yang baik untuk memperkirakan hit cache.
Cara build menggunakan cache jarak jauh
Setelah server disiapkan sebagai {i>cache<i} jarak jauh, Anda menggunakan {i>cache<i} di beberapa cara:
- Membaca dan menulis ke cache jarak jauh
- Membaca dan/atau menulis ke cache jarak jauh kecuali untuk target tertentu
- Hanya baca dari cache jarak jauh
- Tidak menggunakan cache jarak jauh sama sekali
Saat Anda menjalankan {i>build<i} Bazel yang dapat membaca dan menulis ke {i>cache<i} jarak jauh, build mengikuti langkah-langkah berikut:
- Bazel membuat grafik target yang perlu dibangun, kemudian membuat daftar tindakan yang diperlukan. Setiap tindakan ini telah mendeklarasikan input dan nama file output.
- Bazel memeriksa komputer lokal untuk menemukan output build yang ada dan menggunakan kembali output build yang ada. yang ditemukannya.
- Bazel memeriksa cache untuk output build yang ada. Jika {i>output<i} itu ditemukan, Bazel akan mengambil output. Ini cache ditemukan.
- Untuk tindakan yang diperlukan apabila {i>output<i} tidak ditemukan, Bazel mengeksekusi tindakan secara lokal dan membuat output build yang diperlukan.
- Output build baru diupload ke cache jarak jauh.
Menyiapkan server sebagai backend cache
Anda harus menyiapkan server untuk bertindak sebagai backend cache. HTTP/1.1 server dapat memperlakukan data Bazel sebagai byte buram dan banyak server yang ada dapat digunakan sebagai backend {i> caching<i} jarak jauh. Bazel Protokol Cache HTTP adalah protokol yang mendukung dalam cache.
Anda bertanggung jawab untuk memilih, menyiapkan, dan memelihara backend server yang akan menyimpan {i>output<i} yang di-cache. Saat memilih server, pertimbangkan:
- Kecepatan jaringan. Misalnya, jika tim Anda berada di kantor yang sama, Anda mungkin ingin menjalankan server lokal Anda sendiri.
- Keamanan. Cache jarak jauh akan memiliki biner Anda, sehingga harus aman.
- Kemudahan pengelolaan. Misalnya, Google Cloud Storage adalah layanan terkelola sepenuhnya.
Ada banyak backend yang dapat digunakan untuk cache jarak jauh. Beberapa opsi termasuk:
nginx
nginx adalah server web {i>open source<i}. Dengan [modul WebDAV], alat ini dapat
digunakan sebagai {i>cache<i} jarak jauh untuk Bazel. Pada Debian dan Ubuntu Anda dapat menginstal
nginx-extras
. Di macOS, nginx tersedia melalui Homebrew:
brew tap denji/nginx
brew install nginx-full --with-webdav
Di bawah ini adalah contoh konfigurasi untuk nginx. Perhatikan bahwa Anda perlu
ubah /path/to/cache/dir
ke direktori yang valid tempat nginx memiliki izin
untuk menulis dan membaca. Anda mungkin perlu mengubah opsi client_max_body_size
menjadi
nilai yang lebih besar jika Anda memiliki
file {i>output<i} yang lebih besar. Server akan memerlukan
konfigurasi lain, seperti otentikasi.
Contoh konfigurasi untuk bagian server
di nginx.conf
:
location /cache/ {
# The path to the directory where nginx should store the cache contents.
root /path/to/cache/dir;
# Allow PUT
dav_methods PUT;
# Allow nginx to create the /ac and /cas subdirectories.
create_full_put_path on;
# The maximum size of a single file.
client_max_body_size 1G;
allow all;
}
bazel-remote
bazel-remote adalah {i>cache<i} {i>open source<i} jarak jauh yang dapat Anda gunakan infrastruktur Anda. telah berhasil digunakan dalam produksi di beberapa perusahaan sejak awal 2018. Perhatikan bahwa proyek Bazel melakukan tidak memberikan dukungan teknis untuk bazel-remote.
Cache ini menyimpan konten pada {i>disk<i} dan juga menyediakan pembersihan sampah memori untuk menerapkan batas penyimpanan atas dan membersihkan artefak yang tidak digunakan. Cache adalah tersedia sebagai [image Docker] dan kodenya tersedia di GitHub. API cache jarak jauh REST dan gRPC didukung.
Buka GitHub untuk petunjuk cara menggunakannya.
Google Cloud Storage
[Google Cloud Storage] adalah penyimpanan objek yang terkelola sepenuhnya yang menyediakan API HTTP yang kompatibel dengan protokol caching jarak jauh Bazel. Memerlukan bahwa Anda memiliki akun Google Cloud dengan penagihan diaktifkan.
Untuk menggunakan Cloud Storage sebagai cache:
Membuat bucket penyimpanan. Pastikan untuk memilih lokasi bucket yang terdekat dengan Anda, sebagai bandwidth jaringan adalah hal penting untuk {i>cache<i} jarak jauh.
Buat akun layanan untuk Bazel guna melakukan autentikasi ke Cloud Storage. Lihat Membuat akun layanan.
Membuat kunci JSON rahasia, lalu meneruskannya ke Bazel untuk autentikasi. Menyimpan kunci itu dengan aman, karena siapa pun yang memiliki kunci tersebut dapat membaca dan menulis data arbitrer ke/dari bucket GCS Anda.
Hubungkan ke Cloud Storage dengan menambahkan flag berikut ke perintah Bazel Anda:
- Teruskan URL berikut ke Bazel dengan menggunakan tanda:
--remote_cache=https://storage.googleapis.com/bucket-name
denganbucket-name
adalah nama bucket penyimpanan Anda. - Teruskan kunci autentikasi menggunakan flag:
--google_credentials=/path/to/your/secret-key.json
, atau--google_default_credentials
untuk menggunakan Autentikasi Aplikasi.
- Teruskan URL berikut ke Bazel dengan menggunakan tanda:
Anda dapat mengonfigurasi Cloud Storage agar otomatis menghapus file lama. Untuk melakukannya, lihat Mengelola Siklus Proses Objek.
Server lainnya
Anda dapat mengatur server HTTP/1.1 yang mendukung PUT dan GET sebagai server backend. Pengguna telah melaporkan keberhasilan dengan backend caching seperti Hazelcast, Apache httpd, dan AWS S3.
Autentikasi
Pada versi 0.11.0 dukungan untuk Otentikasi Dasar HTTP telah ditambahkan ke Bazel.
Anda dapat meneruskan nama pengguna dan sandi ke Bazel melalui URL cache jarak jauh. Tujuan
sintaksisnya adalah https://username:password@hostname.com:port/path
. Perlu diketahui bahwa
Autentikasi Dasar HTTP mengirimkan nama pengguna dan {i>password<i} dalam teks polos melalui
jaringan sehingga penting untuk selalu
menggunakannya dengan HTTPS.
Protokol caching HTTP
Bazel mendukung pembuatan cache jarak jauh melalui HTTP/1.1. Protokolnya sederhana secara konsep:
Data biner (BLOB) diupload melalui permintaan PUT dan didownload melalui permintaan GET.
Metadata hasil tindakan disimpan di jalur /ac/
dan file output disimpan
pada jalur /cas/
.
Misalnya, pertimbangkan cache jarak jauh yang berjalan di http://localhost:8080/cache
.
Permintaan Bazel untuk mendownload metadata hasil tindakan bagi tindakan dengan SHA256
hash 01ba4719...
akan terlihat seperti berikut:
GET /cache/ac/01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b HTTP/1.1
Host: localhost:8080
Accept: */*
Connection: Keep-Alive
Permintaan Bazel untuk mengupload file output dengan hash SHA256 15e2b0d3...
ke
CAS akan terlihat seperti berikut:
PUT /cache/cas/15e2b0d3c33891ebb0f1ef609ec419420c20e320ce94c65fbc8c3312448eb225 HTTP/1.1
Host: localhost:8080
Accept: */*
Content-Length: 9
Connection: Keep-Alive
0x310x320x330x340x350x360x370x380x39
PERINGATAN: Membangun tanpa Byte tidak kompatibel dengan cache HTTP. Untuk mendapatkan peningkatan kinerja yang maksimal, sebaiknya gunakan cache gRPC.
Menjalankan Bazel menggunakan cache jarak jauh
Setelah server disiapkan sebagai {i>cache<i} jarak jauh, untuk menggunakan {i>cache<i} jarak jauh perlu menambahkan penanda ke perintah Bazel Anda. Lihat daftar konfigurasi dan penanda mereka di bawah ini.
Anda mungkin juga perlu mengonfigurasi autentikasi, yang dikhususkan untuk server yang dipilih.
Anda mungkin ingin menambahkan tanda ini dalam file .bazelrc
agar
perlu menentukannya
setiap kali Anda menjalankan Bazel. Tergantung pada
proyek dan
dinamika tim, Anda dapat menambahkan flag ke file .bazelrc
yang:
- Di komputer lokal Anda
- Di ruang kerja project Anda, dibagikan kepada tim
- Pada sistem CI
Membaca dari dan menulis ke cache jarak jauh
Berhati-hatilah terhadap siapa yang memiliki kemampuan untuk menulis ke cache jarak jauh. Mungkin Anda ingin sistem CI Anda yang dapat menulis ke {i>cache<i} jarak jauh.
Gunakan tanda berikut untuk membaca dari dan menulis ke cache jarak jauh:
build --remote_cache=http://your.host:port
Selain HTTP
, protokol berikut juga didukung: HTTPS
, grpc
, grpcs
.
Gunakan flag berikut selain yang di atas untuk hanya membaca dari cache jarak jauh:
build --remote_upload_local_results=false
Mengecualikan target tertentu agar tidak menggunakan cache jarak jauh
Untuk mengecualikan target tertentu agar tidak menggunakan cache jarak jauh, beri tag target dengan
no-remote-cache
. Contoh:
java_library(
name = "target",
tags = ["no-remote-cache"],
)
Menghapus konten dari cache jarak jauh
Menghapus konten dari cache jarak jauh adalah bagian dari pengelolaan server Anda. Cara menghapus konten dari cache jarak jauh bergantung pada server yang Anda miliki siapkan sebagai cache. Saat menghapus {i>output<i}, hapus seluruh {i>cache<i}, atau menghapus {i>output<i} lama.
Output yang di-cache disimpan sebagai sekumpulan nama dan hash. Saat menghapus konten, tidak ada cara untuk membedakan {i>output<i} mana yang dimiliki oleh buat.
Anda dapat menghapus konten dari cache untuk:
- Membuat cache bersih setelah cache diubah
- Mengurangi jumlah penyimpanan yang digunakan dengan menghapus output lama
Soket Unix
Cache HTTP jarak jauh mendukung koneksi melalui soket domain unix. Perilaku
mirip dengan flag --unix-socket
curl. Gunakan perintah berikut untuk mengonfigurasi unix
soket domain:
build --remote_cache=http://your.host:port
build --remote_proxy=unix:/path/to/socket
Fitur ini tidak didukung di Windows.
Cache disk
Bazel dapat menggunakan direktori pada sistem file sebagai {i>cache<i} jarak jauh. Ini adalah berguna untuk membagikan artefak build saat beralih cabang dan/atau bekerja di beberapa ruang kerja dari project yang sama, seperti beberapa checkout. Sejak Bazel tidak melakukan pembersihan sampah memori pada direktori, Anda mungkin ingin mengotomatisasi pembersihan berkala direktori ini. Aktifkan cache disk sebagai berikut:
build --disk_cache=path/to/build/cache
Anda dapat meneruskan jalur khusus pengguna ke tanda --disk_cache
menggunakan alias ~
(Bazel akan mengganti direktori beranda pengguna saat ini). Hal ini berguna
saat mengaktifkan cache disk untuk semua developer project melalui
telah diperiksa dalam .bazelrc
file.
Masalah umum
Modifikasi file input selama build
Bila file input diubah selama build, Bazel mungkin mengupload file
ke cache jarak jauh. Anda dapat mengaktifkan deteksi perubahan dengan
flag --experimental_guard_against_concurrent_changes
. Ada
bukan masalah umum dan akan diaktifkan secara default pada rilis mendatang.
Lihat [masalah #3360] untuk mengetahui info terbaru. Secara umum, hindari memodifikasi {i>file<i} sumber selama
buat.
Variabel lingkungan bocor ke dalam tindakan
Definisi tindakan berisi variabel lingkungan. Hal ini bisa menjadi
masalah bagi
berbagi cache jarak jauh
di seluruh komputer. Misalnya, lingkungan dengan
variabel $PATH
yang berbeda tidak akan membagikan hit cache. Hanya variabel lingkungan
secara eksplisit diizinkan melalui --action_env
disertakan dalam tindakan
definisi. Paket Debian/Ubuntu Bazel digunakan untuk menginstal /etc/bazel.bazelrc
dengan daftar variabel lingkungan yang diizinkan, termasuk $PATH
. Jika Anda mendapatkan
lebih sedikit ditemukan cache dari yang diperkirakan, periksa apakah lingkungan Anda tidak memiliki
File /etc/bazel.bazelrc
.
Bazel tidak memantau alat di luar ruang kerja
Bazel saat ini tidak memantau alat di luar ruang kerja. Hal ini dapat berupa
masalah jika, misalnya, tindakan menggunakan compiler dari /usr/bin/
. Lalu:
dua pengguna dengan compiler yang berbeda terinstal akan salah membagikan hit cache
karena {i>output-<i}nya berbeda tetapi
memiliki {i>hash<i} tindakan yang sama. Lihat
masalah #4558 untuk mendapatkan info terbaru.
Status inkremental dalam memori hilang saat menjalankan build di dalam container docker Bazel menggunakan arsitektur server/klien bahkan saat berjalan di container docker tunggal. Di sisi server, Bazel mempertahankan status dalam memori yang mempercepat build. Saat menjalankan build di dalam container docker seperti di CI, status dalam memori akan hilang dan Bazel harus membuatnya ulang sebelum menggunakan {i>cache<i} jarak jauh.
Link eksternal
Build Anda di Pusat Data: Tim Bazel membahas pembicaraan tentang penyimpanan dan eksekusi cache jarak jauh di FOSDEM 2018.
Lebih cepat Bazel dibangun dengan cache jarak jauh: sebuah tolok ukur: Nicolò Valigi menulis postingan blog di mana ia melakukan benchmark {i> caching<i} jarak jauh di Bazel.