Uzaktan Önbelleğe Alma

Sorun bildirin Kaynağı göster

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

Uzak önbellek, derleme çıkışlarını paylaşmak için bir geliştirici ekibi ve/veya sürekli entegrasyon (CI) sistemi tarafından kullanılır. Derlemeniz yeniden oluşturulabilirse bir makineden elde edilen çı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şlemin girişleri, çıkış adları, komut satırı ve ortam değişkenleri vardır. Her işlem için gerekli girişler ve beklenen çıkışlar 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 ve içeriklerinin karmalarından oluşan bir listeden oluşur. Uzak önbellek sayesinde her yeni çıkışı yerel olarak oluşturmak 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ü kullanın

Uzak önbellek iki tür veri depolar:

  • İşlem karmalarının işlem sonucu meta verilerine yönelik bir haritası olan işlem önbelleği.
  • Çıkış dosyalarının içeriğiyle ilgili adreslenebilir bir depo (CAS).

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

Bir derleme uzaktan önbelleğe almayı nasıl kullanır?

Bir sunucu uzak önbellek olarak ayarlandıktan sonra önbelleği birkaç şekilde kullanırsınız:

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

Uzak önbelleği okuyabilen ve ona yazabilen bir Bazel derlemesi çalıştırdığınızda derleme şu 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 makinenizi mevcut derleme çıkışları için kontrol eder ve bulduklarını yeniden kullanır.
  3. Bazel, mevcut derleme çıkışları için önbelleği kontrol eder. Çıkış bulunursa Bazel, çıktı alır. Bu bir ö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 çıkışları, uzak önbelleğe yüklenir.

Önbelleğin arka ucu olarak sunucu ayarlama

Önbelleğin arka ucu olarak işlev görecek bir sunucu kurmanı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 şunları 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 bulunur ve bu nedenle güvenli olmaları gerekir.
  • Yönetim kolaylığı. Ö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ü] ile 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 öğesini, nginx'in yazma ve okuma izninin 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 bir yapılandırmaya gerekir.

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

bazel-remote, altyapınızda kullanabileceğiniz açık kaynaklı bir uzak derleme önbelleğidir. 2018'in başından beri birçok şirkette ü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 alanı sınırı uygulamak ve kullanılmayan yapıları temizlemek için atık toplama sağlar. Önbellek [docker görüntüsü] olarak ve kodu GitHub'da mevcuttur. Hem REST hem de gRPC uzak önbellek API'leri desteklenir.

Bu SDK'yı nasıl kullanacağınızla ilgili talimatlar için GitHub sayfasına bakın.

Google Cloud Storage

[Google Cloud Storage], Bazel'in uzaktan önbelleğe alma protokolüyle uyumlu olan bir HTTP API sağlayan, tümüyle yönetilen bir nesne deposudur. Bunun için faturalandırmanın etkin olduğu bir Google Cloud hesabınızın olması gerekir.

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

  1. Depolama 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. Cloud Storage'da kimlik doğrulaması yapmak üzere Bazel için bir hizmet hesabı oluşturun. Hizmet hesabı oluşturma sayfasına göz atın.

  3. Gizli bir JSON anahtarı oluşturun ve kimlik doğrulaması için bunu Bazel'a iletin. Anahtara sahip herkes GCS paketinize rastgele veri okuyup yazabileceğinden anahtarı güvenli bir şekilde depolayın.

  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.
    • Şu işareti kullanarak kimlik doğrulama anahtarını iletin: --google_credentials=/path/to/your/secret-key.json veya Uygulama Kimlik Doğrulaması'nı kullanmak için --google_default_credentials.

  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

Önbelleğin arka ucu olarak PUT ve GET'yi destekleyen herhangi bir HTTP/1.1 sunucusu oluşturabilirsiniz. Kullanıcılar; Hazelcast, Apache httpd ve AWS S3 gibi önbelleğe alma arka uçlarının başarılı olduğunu bildirmiştir.

Kimlik doğrulama

0.11.0 sürümünden itibaren Bazel'e HTTP Temel Kimlik Doğrulaması için destek eklendi. Uzak önbellek URL'si aracılığıyla Bazel'a bir kullanıcı adı ve şifre aktarabilirsiniz. Söz dizimi https://username:password@hostname.com:port/path şeklindedir. Temel HTTP Kimlik Doğrulaması'nın, kullanıcı adını ve şifreyi ağ üzerinden düz metin olarak ilettiğini unutmayın. Bu nedenle, bunların her zaman HTTPS ile kullanılması çok önemlidir.

HTTP önbelleğe alma protokolü

Bazel, HTTP/1.1 aracılığıyla 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/ yolu altında depolanır.

Örneğin, http://localhost:8080/cache altında çalışan bir uzak önbellek 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'ye 15e2b0d3... SHA256 karmasına sahip çıkış dosyası yüklemeyle ilgili bir 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'ı uzak önbelleği kullanarak çalıştırma

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

Seçtiğiniz sunucuya özgü kimlik doğrulamasını da yapılandırmanız gerekebilir.

Bazel'i her çalıştırdığınızda bunları belirtmek zorunda kalmamak için bu işaretleri bir .bazelrc dosyasına ekleyebilirsiniz. Projenize ve ekip dinamiklerinize bağlı olarak, aşağıdaki özelliklere sahip bir .bazelrc dosyasına işaret ekleyebilirsiniz:

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

Uzak önbelleğe alma ve uzak önbelleğe yazma

Uzak önbelleğe kimlerin yazabileceğine dikkat edin. Uzak önbelleğe yalnızca CI sisteminizin yazabilmesini isteyebilirsiniz.

Uzak önbelleğe almak ve önbelleğe almak 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 uzaktan önbellekten okumak için yukarıdaki işarete ek olarak aşağıdaki işareti de kullanın:

build --remote_upload_local_results=false

Belirli hedefleri uzak önbellekten hariç tutun

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

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

Uzak önbellekten içerik silin

Uzak önbellekten içerik silmek, sunucunuzu yönetme işleminin bir parçasıdır. Uzak önbellekteki içeriği nasıl sileceğiniz, ö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 bir ad ve karma grubu olarak depolanır. İçerik silinirken hangi çıkışın belirli bir derlemeye ait olduğunu ayırt etmenin bir yolu yoktur.

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ı miktarını azaltın

Unix prizler

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

   build --remote_cache=http://your.host:port
   build --remote_cache_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 birden fazla ödeme gibi aynı projenin birden fazla çalışma alanında çalışırken derleme yapılarını paylaşmak için faydalıdır. Bazel, dizini gereksiz yere toplamadığından, bu dizinin düzenli aralıklarla temizlenmesini otomatik hale getirmek isteyebilirsiniz. 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 özellik, projenin kontrol edilen .bazelrc dosyası aracılığıyla projenin tüm geliştiricileri için disk önbelleğini etkinleştirirken kullanışlıdır.

Bilinen sorunlar

Derleme sırasında dosya değişikliği girme

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. Genel olarak, derleme sırasında kaynak dosyaları değiştirmekten kaçının.

İşleme sızdıran ortam değişkenleri

İşlem tanımı ortam değişkenlerini içerir. Bu, uzak önbellek isabetlerinin makineler arasında paylaşılmasında bir sorun olabilir. Örneğin, farklı $PATH değişkenlerine sahip ortamlar önbellek isabetlerini 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. $PATH dahil olmak üzere ortam değişkenlerinin beyaz listesiyle /etc/bazel.bazelrc yüklemek için Bazel'in Debian/Ubuntu paketi kullanılıyordu. Beklenenden daha az önbellek isabeti alıyorsanız ortamınızda eski bir /etc/bazel.bazelrc dosyası olmadığından emin olun.

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

Bazel şu anda çalışma alanının dışındaki araçları izlememektedir. Bu durum, örneğin bir işlemde /usr/bin/ hizmetindeki bir derleyici kullanılıyorsa sorun olabilir. 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 sorun #4558'e 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. Sunucu tarafında Bazel, derlemeleri hızlandıran bir bellek içi durumu sağlar. CI gibi Docker container'larının içinde derlemeler çalıştırırken bellek içi durum kaybedilir ve Bazel'in uzak önbelleği kullanmadan önce bunu yeniden oluşturması gerekir.