Uzaktan Önbelleğe Alma

Sorun bildir Kaynağı görüntüle Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

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

Uzak önbellek, derleme çıktılarını paylaşmak için bir geliştirici ekibi ve/veya sürekli entegrasyon (CI) sistemi tarafından kullanılır. Derlemeniz yeniden üretilebiliyorsa bir makinedeki çıktılar başka bir makinede güvenle yeniden kullanılabilir. Bu da derlemelerin önemli ölçüde hızlanmasını sağlayabilir.

Genel Bakış

Bazel, derlemeyi işlemler adı verilen ayrı adımlara böler. Her işlemin girişleri, çıkış adları, komut satırı ve ortam değişkenleri vardır. Gerekli girişler ve beklenen çıkışlar her işlem için açıkça belirtilir.

Bu işlem çıkışları olan derleme çıkışları için uzak önbellek olarak kullanılacak bir sunucu ayarlayabilirsiniz. Bu çıktılar, çıkış dosyası adlarının listesinden ve içeriklerinin karma değerlerinden oluşur. Uzak önbellek sayesinde, her yeni çıkışı yerel olarak derlemek yerine başka bir kullanıcının derlemesindeki derleme çıkışlarını yeniden kullanabilirsiniz.

Uzaktan önbelleğe alma özelliğini kullanmak için:

  • Sunucuyu önbelleğin arka ucu olarak ayarlama
  • Bazel derlemesini uzak önbelleği kullanacak şekilde yapılandırma
  • Bazel 0.10.0 veya sonraki bir sürümünü 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ğe göre adreslenebilir deposu (CAS).

Uzak önbelleğin, her işlem için stdout ve stderr'yi de depoladığını unutmayın. Bu nedenle, Bazel'in stdout/stderr'ını incelemek, önbellek isabetlerini tahmin etmek için iyi bir sinyal değildir.

Derlemeler, uzak önbelleğe almayı nasıl kullanır?

Bir sunucu uzak önbellek olarak ayarlandıktan sonra önbelleği çeşitli şekillerde kullanabilirsiniz:

  • Uzak önbelleğe okuma ve yazma
  • Belirli hedefler hariç olmak üzere uzak önbelleğe okuma ve/veya yazma
  • Yalnızca uzak önbellekten okuma
  • Uzak önbelleği hiç kullanmayın

Uzak önbelleğe okuma ve yazma işlemleri yapabilen bir Bazel derlemesi çalıştırdığınızda derleme şu adımları izler:

  1. Bazel, oluşturulması gereken hedeflerin grafiğini oluşturur ve ardından gerekli işlemlerin listesini oluşturur. Bu işlemlerin her birinin belirtilmiş 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. Çıkış bulunursa Bazel, çıkışı alır. Bu, önbellek isabetidir.
  4. Çıkışların bulunamadığı gerekli işlemler için Bazel, işlemleri yerel olarak yürütür ve gerekli derleme çıkışlarını oluşturur.
  5. Yeni derleme çıktıları uzak önbelleğe yüklenir.

Sunucuyu önbelleğin arka ucu olarak ayarlama

Önbelleğin arka ucu olarak işlev görecek bir sunucu ayarlamanız gerekir. Bir HTTP/1.1 sunucusu, Bazel'in verilerini opak baytlar olarak değerlendirebilir. Bu nedenle, mevcut birçok sunucu uzak önbelleğe alma arka ucu olarak kullanılabilir. Uzak önbelleğe almayı destekleyen, Bazel'in HTTP önbelleğe alma protokolüdür.

Önbelleğe alınmış çıktıları depolayacak arka uç sunucusunu seçmek, ayarlamak ve bakımını yapmak sizin sorumluluğunuzdadır. Sunucu seçerken şunları göz önünde bulundurun:

  • Ağ hızı. Örneğin, ekibiniz aynı ofiste çalışıyorsa kendi yerel sunucunuzu çalıştırmak isteyebilirsiniz.
  • Güvenlik. Uzak önbellekte ikili dosyalarınız bulunur ve bu nedenle güvenli olması gerekir.
  • Kolay yönetim. Örneğin, Google Cloud Storage tümüyle yönetilen bir hizmettir.

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

nginx

nginx, açık kaynaklı bir web sunucusudur. [WebDAV modülü] sayesinde Bazel için uzaktan önbellek olarak kullanılabilir. Debian ve Ubuntu'da nginx-extras paketini yükleyebilirsiniz. macOS'te nginx, Homebrew aracılığıyla 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ğerle değiştirmeniz gerekebilir. Sunucu, kimlik doğrulama gibi başka yapılandırmalar gerektirir.

nginx.conf içindeki 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-remote

bazel-remote, altyapınızda kullanabileceğiniz açık kaynaklı bir uzak derleme önbelleğidir. 2018'in başlarından beri ç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çerikleri diskte depolar ve ayrıca üst depolama sınırını zorunlu kılmak ve kullanılmayan yapıları temizlemek için çöp toplama işlemi gerçekleştirir. Ö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ını inceleyin.

Google Cloud Storage

[Google Cloud Storage], Bazel'in uzaktan önbelleğe alma protokolüyle uyumlu bir HTTP API'si sağlayan, tamamen yönetilen bir nesne deposudur. Faturalandırmanın etkin olduğu bir Google Cloud hesabınızın olması gerekir.

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

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

  2. Bazel'in Cloud Storage'te kimliğini doğrulaması için bir hizmet hesabı oluşturun. Hizmet hesabı oluşturma başlıklı makaleye bakın.

  3. Gizli bir JSON anahtarı oluşturun ve ardından kimlik doğrulama için Bazel'e iletin. Anahtarı güvenli bir şekilde saklayın. Anahtara sahip olan herkes GCS paketinize rastgele veriler okuyup yazabilir.

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

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

  5. Cloud Storage'ı eski dosyaları otomatik olarak silecek şekilde yapılandırabilirsiniz. Bunun için Nesne Yaşam Döngülerini Yönetme başlıklı makaleyi 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 alarak başarılı sonuçlar elde ettiklerini bildirmiştir.

Kimlik doğrulama

0.11.0 sürümünden itibaren Bazel'e HTTP temel kimlik doğrulaması desteği eklendi. Uzak önbellek 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 birlikte kullanmanın kritik önem taşıdığını unutmayın.

HTTP önbelleğe alma protokolü

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

Örneğin, http://localhost:8080/cache altında çalışan bir uzak önbelleği ele alalım. SHA256 hash değeri 01ba4719... olan bir işlem için işlem sonucu meta verilerini indirmeye yönelik 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'ye 15e2b0d3... SHA256 karmasıyla 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

Uzak önbelleği kullanarak Bazel'i ç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.

Ayrıca, seçtiğiniz sunucuya özel olan kimlik doğrulamayı da yapılandırmanız gerekebilir.

Bu işaretleri .bazelrc dosyasına ekleyerek Bazel'i her çalıştırdığınızda belirtmeniz gerekmez. Projenize ve ekibinizin dinamiklerine bağlı olarak, .bazelrc dosyasına aşağıdaki gibi işaretler ekleyebilirsiniz:

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

Uzak önbellekten okuma ve uzak önbelleğe yazma

Uzak önbelleğe yazma izni olan kişilere dikkat edin. Uzak önbelleğe yalnızca CI sisteminizin yazabilmesini isteyebilirsiniz.

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

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

HTTP dışında şu 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 hedeflerin uzak önbelleği kullanmasını engelleme

Belirli hedeflerin uzaktan önbelleği kullanmasını engellemek için hedefi no-remote-cache ile etiketleyin. Örneğin:

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

Uzak önbellekten içeriği silme

İçeriği uzak önbellekten silmek, sunucunuzu yönetmenin bir parçasıdır. Uzak önbellekten içerik silme şekliniz, önbellek olarak ayarladığınız sunucuya bağlıdır. Çıkışları silerken önbelleğin tamamını veya eski çıkışları silebilirsiniz.

Önbelleğe alınan çıkışlar, bir ad ve karma kümesi olarak saklanır. İçerik silinirken hangi çıkışın belirli bir derlemeye ait olduğunu ayırt etmenin bir yolu yoktur.

Aşağıdaki nedenlerle önbellekteki içerikleri silmek isteyebilirsiniz:

  • Önbellek zehirlendikten sonra temiz bir önbellek oluşturma
  • Eski çıktıları silerek kullanılan depolama alanını azaltma

Unix soketleri

Uzak HTTP önbelleği, Unix alan adı soketleri üzerinden bağlantıyı destekler. Bu davranış, curl'ün --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'da desteklenmez.

Disk önbelleği

Bazel, dosya sistemindeki bir dizini uzak önbellek olarak kullanabilir. Bu, dallar arasında geçiş yaparken ve/veya aynı projenin birden fazla çalışma alanında (ör. birden fazla ödeme) çalışırken derleme yapılarını paylaşmak için kullanışlı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 iletebilirsiniz (Bazel, mevcut kullanıcının ana dizinini değiştirir). Bu, projenin .bazelrc dosyası aracılığıyla bir projenin tüm geliştiricileri için disk önbelleğini etkinleştirirken kullanışlıdır.

Atık toplama

Bazel 7.4'ten itibaren, disk önbelleği veya tek tek önbellek girişlerinin yaşı için maksimum boyut belirlemek üzere --experimental_disk_cache_gc_max_size ve --experimental_disk_cache_gc_max_age kullanabilirsiniz. Bazel, derlemeler arasında boşta kalırken disk önbelleğini otomatik olarak çöp toplama işlemine tabi tutar. Boşta kalma zamanlayıcısı --experimental_disk_cache_gc_idle_delay ile ayarlanabilir (varsayılan olarak 5 dakika).

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

Bilinen sorunlar

Derleme sırasında giriş dosyasında yapılan değişiklikler

Bir derleme sırasında giriş dosyası değiştirildiğinde Bazel, uzak önbelleğe geçersiz sonuçlar yükleyebilir. --experimental_guard_against_concurrent_changes işaretini kullanarak değişiklik algılamayı etkinleştirebilirsiniz. Bilinen bir sorun yoktur ve gelecekteki bir sürümde varsayılan olarak etkinleştirilecektir. Güncellemeler için [issue #3360] başlıklı makaleyi inceleyin. Genellikle, derleme sırasında kaynak dosyaları değiştirmeyin.

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

İşlem tanımı ortam değişkenleri içerir. Bu durum, makineler arasında uzak önbellek isabetlerinin paylaşılması açısından sorun teşkil edebilir. Örneğin, farklı $PATH değişkenlerine sahip ortamlar, önbellek isabetlerini paylaşmaz. Bir işlem tanımına yalnızca --action_env aracılığıyla açıkça izin verilen ortam değişkenleri dahil edilir. Bazel'in Debian/Ubuntu paketi, /etc/bazel.bazelrc ortam değişkenlerinin beyaz listesiyle birlikte yüklenmek için kullanılır. Bu liste $PATH değişkenini içerir. Beklenenden daha az önbellek isabeti alıyorsanız ortamınızda eski bir /etc/bazel.bazelrc dosyası olup olmadığını kontrol edin.

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

Bazel şu anda çalışma alanı dışındaki araçları izlemez. Örneğin, bir işlem /usr/bin/'daki bir derleyiciyi kullanıyorsa bu durum sorun yaratabilir. Ardından, farklı derleyicilerin yüklü olduğu iki kullanıcı, çıkışlar farklı olmasına rağmen aynı işlem karmasına sahip oldukları için önbellek isabetlerini yanlışlıkla paylaşır. Güncellemeler için 4558 numaralı soruna bakın.

Derlemeler Docker kapsayıcılarında çalıştırıldığında artımlı bellek içi durum kayboluyor Bazel, tek bir Docker kapsayıcısında çalıştırıldığında bile sunucu/istemci mimarisini kullanır. Bazel, sunucu tarafında derlemeleri hızlandıran bir bellek içi durum tutar. CI gibi Docker container'larında derlemeler çalıştırılırken bellek içi durum kaybolur ve Bazel, uzak önbelleği kullanmadan önce bu durumu yeniden oluşturmalıdır.