Uzaktan Önbelleğe Alma

Sorun bildir Kaynağı görüntüleyin Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Bu sayfada uzak önbelleğe alma, önbelleği barındıracak bir sunucu oluşturma ve uzak önbelleği kullanarak derleme çalıştırma konuları ele alınmaktadır.

Uzak önbelleğe alma, geliştirici ekibi ve/veya sürekli entegrasyon (CI) sistemi tarafından derleme sonuçlarını paylaşmak için kullanılır. Derlemeniz yeniden üretilebiliyorsa bir makinedeki çıkışlar başka bir makinede güvenli bir şekilde yeniden kullanılabilir. Bu da derlemeleri önemli ölçüde hızlandırabilir.

Genel Bakış

Bazel, bir yapıyı işlem adı verilen ayrı adımlara böler. Her işlemde girişler, çıkış adları, komut satırı ve ortam değişkenleri bulunur. Zorunlu girişler ve beklenen çıkışlar her işlem için açıkça belirtilir.

Bir sunucuyu, derleme çıkışları olan uzak önbellek (bu işlem çıkışları) için ayarlayabilirsiniz. Bu çıkışlar, çıkış dosyası adlarının listesinden ve içeriklerinin karma değerlerinden oluşur. Uzak önbelleği kullanarak, her yeni çıktıyı yerel olarak derlemek yerine başka bir kullanıcının derlemesinden gelen derleme çıktılarını yeniden kullanabilirsiniz.

Uzaktan önbelleğe almayı kullanmak için:

  • Önbelleğin arka ucu olarak bir sunucu ayarlama
  • Bazel derlemesini uzak önbelleği kullanacak şekilde yapılandırma
  • Bazel 0.10.0 veya sonraki bir sürümü kullanın

Uzak önbellekte iki tür veri depolanır:

  • İşlem karmalarının işlem sonucu meta verileriyle eşlendiği bir harita olan işlem önbelleği.
  • Çıkış dosyalarının içeriğiyle ilgili adreslenebilir bir depo (CAS).

Uzaktan önbelleğin her işlem için stdout ve stderr'yi de depoladığını unutmayın. Bu nedenle, Bazel'in stdout/stderr değerini incelemek önbelleğe isabet sayısını tahmin etmek için iyi bir sinyal değildir.

Derlemelerde uzak önbelleğe alma nasıl kullanılır?

Uzak önbellek olarak ayarlanan bir sunucuyu birden fazla şekilde kullanabilirsiniz:

  • Uzak önbelleği okuma ve yazma
  • Belirli hedefler hariç uzak önbelleği okuma ve/veya yazma
  • Yalnızca uzak önbellekten okuma
  • Uzak önbelleği hiç kullanma

Uzaktan önbelleğe okuma ve yazma yapabilen bir Bazel derlemesi çalıştırdığınızda derleme aşağıdaki adımları uygular:

  1. Bazel, oluşturulması gereken hedeflerin grafiğini ve ardından gerekli işlemlerin listesini oluşturur. Bu işlemlerin her birinin tanımlanmış girişleri ve çıkış dosya adları vardır.
  2. Bazel, yerel makinenizde mevcut derleme çıkışlarını kontrol eder ve bulduğu çıkışları yeniden kullanır.
  3. Bazel, mevcut derleme çıkışları için önbelleği kontrol eder. Sonuç bulunursa Bazel sonucu alır. Bu bir önbellek isabetidir.
  4. Bazel, çıkışların bulunamadığı gerekli işlemler için işlemleri yerel olarak yürütür ve gerekli derleme çıkışlarını oluşturur.
  5. Yeni derleme çıkışları uzak önbelleğe yüklenir.

Önbelleğin arka ucu olarak sunucu ayarlama

Önbelleğin arka ucu olarak kullanılacak bir sunucu oluşturmanız gerekir. HTTP/1.1 sunucusu, Bazel'ın verilerini opak bayt olarak işleme alabilir ve mevcut pek çok sunucu, uzak önbelleğe alma arka ucu olarak kullanılabilir. Bazel'in HTTP Önbelleğe Alma Protokolü, uzaktan önbelleğe almayı destekler.

Önbelleğe alınan çıkışları depolayacak arka uç sunucusunu seçmek, ayarlamak ve sürdürmekten siz sorumlusunuzdur. Sunucu seçerken aşağıdakileri göz önünde bulundurun:

  • Ağ hızı. Örneğin, ekibiniz aynı ofisteyse kendi yerel sunucunuzu çalıştırabilirsiniz.
  • Güvenlik. Uzak önbellekte ikili dosyalarınız bulunduğundan bu önbelleğin güvenli olması gerekir.
  • Kolay yönetim. Örneğin, Google Cloud Storage tümüyle yönetilen bir hizmettir.

Uzak önbellek için kullanılabilecek birçok arka uç vardır. Bazı seçenekler şunlardır:

nginx

nginx, açık kaynak bir web sunucusudur. [WebDAV modülü] sayesinde Bazel için uzak önbellek olarak kullanılabilir. Debian ve Ubuntu'da nginx-extras paketini yükleyebilirsiniz. macOS'te nginx, Homebrew üzerinden kullanılabilir:

brew tap denji/nginx
brew install nginx-full --with-webdav

Aşağıda nginx için örnek bir yapılandırma verilmiştir. /path/to/cache/dir değerini, nginx'in yazma ve okuma iznine sahip olduğu geçerli bir dizinle değiştirmeniz gerektiğini unutmayın. Daha büyük çıkış dosyalarınız varsa client_max_body_size seçeneğini daha büyük bir değere ayarlamanız gerekebilir. Sunucu için kimlik doğrulama gibi başka yapılandırmalar gerekir.

nginx.conf'daki server bölümü için örnek yapılandırma:

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-uzaktan

bazel-remote, altyapınızda kullanabileceğiniz açık kaynak bir uzak derleme önbelleğidir. 2018'in başlarından bu yana çeşitli şirketlerde üretimde başarıyla kullanılmaktadır. Bazel projesinin bazel-remote için teknik destek sağlamadığını unutmayın.

Bu önbellek, içeriği diskte depolar ve üst depolama sınırını uygulamak ve kullanılmayan yapıları temizlemek için çöp toplama işlemi de sağlar. Önbellek [docker resmi] olarak kullanılabilir ve kodu GitHub'da mevcuttur. Hem REST hem de gRPC uzak önbellek API'leri desteklenir.

Nasıl kullanılacağıyla ilgili talimatlar için GitHub sayfasına bakın.

Google Cloud Storage

[Google Cloud Storage], Bazel'in uzak önbelleğe alma protokolüyle uyumlu bir HTTP API'si sağlayan, tamamen yönetilen bir nesne deposudur. Bunun için faturalandırmanın etkin olduğu bir Google Cloud hesabınız olmalıdır.

Cloud Storage'ı önbellek olarak kullanmak için:

  1. Storage paketi oluşturun. Ağ bant genişliği uzak önbelleğe almak için önemli olduğundan, size en yakın paket konumunu seçtiğinizden emin olun.

  2. Bazel'in Cloud Storage'da kimlik doğrulaması yapması için bir hizmet hesabı oluşturun. Hizmet hesabı oluşturma başlıklı makaleye göz atın.

  3. Gizli bir JSON anahtarı oluşturun ve ardından kimlik doğrulaması için Bazel'e iletin. Anahtarı güvende tutun. Anahtarı olan herkes GCS paketinize/paketinizden rastgele veri okuyabilir ve yazabilir.

  4. Bazel komutunuza aşağıdaki işaretleri ekleyerek Cloud Storage'a bağlanın:

    • İşareti kullanarak şu URL'yi Bazel'a iletin: --remote_cache=https://storage.googleapis.com/bucket-name, burada bucket-name, depolama paketinizin adıdır.
    • Kimlik doğrulama anahtarını --google_credentials=/path/to/your/secret-key.json işaretini kullanarak iletin veya uygulama kimlik doğrulamasını kullanmak için --google_default_credentials işaretini kullanın.

  5. Cloud Storage'ı eski dosyaları otomatik olarak silecek şekilde yapılandırabilirsiniz. Bunu yapmak için Nesne Yaşam Döngülerini Yönetme bölümünü inceleyin.

Diğer sunucular

PUT ve GET'i destekleyen herhangi bir HTTP/1.1 sunucusunu önbelleğin arka ucu olarak ayarlayabilirsiniz. Kullanıcılar Hazelcast, Apache httpd ve AWS S3 gibi arka uçları önbelleğe alma konusunda başarılı olduklarını bildirmiştir.

Kimlik doğrulama

0.11.0 sürümü itibarıyla Bazel'e HTTP Temel Kimlik Doğrulaması desteği eklendi. Uzaktan önbelleğe alma URL'si aracılığıyla Bazel'e kullanıcı adı ve şifre iletebilirsiniz. Söz dizimi https://username:password@hostname.com:port/path. HTTP Temel Kimlik Doğrulaması'nın, kullanıcı adını ve şifreyi ağ üzerinden düz metin olarak ilettiğini ve bu nedenle her zaman HTTPS ile kullanılmasının kritik olduğunu unutmayın.

HTTP önbelleğe alma protokolü

Bazel, HTTP/1.1 aracılığıyla uzaktan önbelleğe almayı destekler. Protokol kavramsal olarak basittir: ikili veriler (BLOB), PUT istekleri aracılığıyla yüklenir ve GET istekleri aracılığıyla indirilir. İşlem sonucu meta verileri /ac/ altında, çıkış dosyaları ise /cas/ altında depolanır.

Örneğin, http://localhost:8080/cache altında çalışan bir uzak önbelleği düşünün. SHA256 karması 01ba4719... olan bir işleme ait işlem sonucu meta verilerini indirme amaçlı bir Bazel isteği aşağıdaki gibi görünür:

GET /cache/ac/01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b HTTP/1.1
Host: localhost:8080
Accept: */*
Connection: Keep-Alive

CAS'e SHA256 karması 15e2b0d3... içeren bir çıkış dosyası yükleme Bazel isteği aşağıdaki gibi görünür:

PUT /cache/cas/15e2b0d3c33891ebb0f1ef609ec419420c20e320ce94c65fbc8c3312448eb225 HTTP/1.1
Host: localhost:8080
Accept: */*
Content-Length: 9
Connection: Keep-Alive

0x310x320x330x340x350x360x370x380x39

Bazel'i uzak önbelleği kullanarak çalıştırma

Bir sunucu uzak önbellek olarak ayarlandıktan sonra uzak önbelleği kullanmak için Bazel komutunuza işaretler eklemeniz gerekir. Yapılandırmaların ve işaretlerinin listesini aşağıda bulabilirsiniz.

Seçtiğiniz sunucuya özel olan kimlik doğrulamayı da yapılandırmanız gerekebilir.

Bazel'i her çalıştırdığınızda belirtmeniz gerekmemesi için bu işaretleri bir .bazelrc dosyasına ekleyebilirsiniz. Projenize ve ekip dinamiklerinize bağlı olarak .bazelrc dosyasına aşağıdaki işaretleri ekleyebilirsiniz:

  • Yerel makinenizde
  • Projenizin çalışma alanında, ekibinizle paylaşılan
  • CI sisteminde

Uzak önbellekten veri okuma ve önbelleğe veri yazma

Uzaktan önbelleğe yazma yetkisi olan kişilere dikkat edin. Yalnızca CI sisteminizin uzak önbelleğe yazabilmesini isteyebilirsiniz.

Uzak önbellekten okumak ve yazmak için aşağıdaki işareti kullanın:

build --remote_cache=http://your.host:port

HTTP'ün yanı sıra aşağıdaki protokoller de desteklenir: HTTPS, grpc, grpcs.

Yalnızca uzak önbellekten okumak için yukarıdakine ek olarak aşağıdaki işareti kullanın:

build --remote_upload_local_results=false

Belirli hedefleri uzak önbelleği kullanmaktan hariç tutma

Belirli hedefleri uzak önbelleği kullanmaktan hariç tutmak için hedefi no-remote-cache ile etiketleyin. Örneğin:

java_library(
    name = "target",
    tags = ["no-remote-cache"],
)

Uzak önbellekten içerik silme

Uzaktan önbellekten içerik silme işlemi, sunucunuzu yönetmenin bir parçasıdır. Uzaktan önbellekten içerik silme işlemi, önbellek olarak ayarladığınız sunucuya bağlıdır. Çıkışları silerken önbelleğin tamamını veya eski çıkışları silin.

Önbelleğe alınan çıkışlar, ad ve karma oluşturma işlemleri grubu olarak saklanır. İçerik silinirken hangi çıktının belirli bir derlemeye ait olduğunu ayırt etmek mümkün değildir.

Aşağıdakileri yapmak için içeriği önbellekten silmek isteyebilirsiniz:

  • Önbellek bozulduktan sonra temiz bir önbellek oluşturma
  • Eski çıkışları silerek kullanılan depolama alanını azaltın

Unix soket

Uzak HTTP önbelleği, unix alan adı yuvaları üzerinden bağlanmayı destekler. Bu davranış, curl'in --unix-socket işaretine benzer. Unix alan soketini yapılandırmak için aşağıdakileri kullanın:

   build --remote_cache=http://your.host:port
   build --remote_proxy=unix:/path/to/socket

Bu özellik Windows'ta desteklenmez.

Disk önbelleği

Bazel, dosya sistemindeki bir dizini uzak önbellek olarak kullanabilir. Bu, dal değiştirirken ve/veya aynı projenin birden fazla çalışma alanında (ör. birden fazla ödeme) çalışırken derleme yapılarını paylaşmak için yararlıdır. Disk önbelleğini aşağıdaki şekilde etkinleştirin:

build --disk_cache=path/to/build/cache

~ takma adını kullanarak --disk_cache işaretine kullanıcıya özel bir yol aktarabilirsiniz (Bazel, geçerli kullanıcının ana dizininin yerini alır). Bu, projenin .bazelrc dosyasında kontrol edilerek projenin tüm geliştiricileri için disk önbelleğini etkinleştirmek istediğinizde kullanışlıdır.

Atık toplama

Bazel 7.4 sürümünden itibaren, disk önbelleği veya bağımsız önbellek girişlerinin yaşı için maksimum boyut ayarlamak üzere --experimental_disk_cache_gc_max_size ve --experimental_disk_cache_gc_max_age kullanabilirsiniz. Bazel, derlemeler arasında boştayken disk önbelleğini otomatik olarak çöp toplar. Boşta kalma zamanlayıcısı --experimental_disk_cache_gc_idle_delay ile ayarlanabilir (varsayılan olarak 5 dakikadır).

Otomatik çöp toplama işlemine alternatif olarak, çöp toplama işlemini isteğe bağlı olarak çalıştırmaya yarayan bir araç da sunuyoruz.

Bilinen sorunlar

Derleme sırasında giriş dosyası değiştirme

Derleme sırasında bir giriş dosyası değiştirildiğinde Bazel, geçersiz sonuçları uzak önbelleğe yükleyebilir. Değişiklik algılamayı --experimental_guard_against_concurrent_changes işaretiyle etkinleştirebilirsiniz. Bilinen bir sorun yoktur ve gelecekteki bir sürümde varsayılan olarak etkinleştirilecektir. Güncellemeler için [sorun numarası 3360] sayfasına göz atın. Genellikle derleme sırasında kaynak dosyalarda değişiklik yapmaktan kaçının.

Ortam değişkenlerinin bir işleme sızması

İşlem tanımı, ortam değişkenleri içerir. Bu, uzak önbellek isabetlerini makineler arasında paylaşırken soruna yol açabilir. Örneğin, farklı $PATH değişkenlerine sahip ortamlar önbelleğe alınan isabetleri paylaşmaz. İşlem tanımına yalnızca --action_env aracılığıyla açıkça beyaz listeye eklenen ortam değişkenleri dahil edilir. Bazel'in Debian/Ubuntu paketi, $PATH dahil olmak üzere ortam değişkenlerinin beyaz listesiyle /etc/bazel.bazelrc yüklemek için kullanılır. Beklediğinizden daha az önbellek isabeti alıyorsanız ortamınızda eski bir /etc/bazel.bazelrc dosyası olup olmadığını kontrol edin.

Bazel, bir çalışma alanının dışındaki araçları izlemez

Bazel şu anda bir çalışma alanının dışındaki araçları izlememektedir. Örneğin, bir işlem /usr/bin/'ten bir derleyici kullanıyorsa bu durum sorun oluşturabilir. Ardından, farklı derleyiciler yüklemiş iki kullanıcı, çıkışlar farklı olmasına rağmen aynı işlem karmasına sahip olduğundan önbellek isabetlerini yanlış bir şekilde paylaşır. Güncellemeler için 4558 numaralı soruna bakın.

Docker container'larında derlemeler çalıştırılırken artımlı bellek içi durum kaybedilir Bazel, tek Docker container'ında çalışırken bile sunucu/istemci mimarisini kullanır. Bazel, sunucu tarafında derlemeleri hızlandıran bellek içi bir durum sürdürür. CI'de olduğu gibi Docker kapsayıcılarında derlemeler çalıştırıldığında bellek içi durum kaybedilir ve Bazel'in uzak önbelleği kullanmadan önce durumu yeniden oluşturması gerekir.