Konteyner kayıt defterlerinin çalışma mantığı: imajları doğrudan Push/Pull etmek

• Konteyner kayıt defteri dışarıdan bakıldığında basit görünür; ancak hatalı etiketler, platform uyumsuzluğu, katman eksikliği veya gerçek silme işleminin başarısız olması gibi sorunları debug etmek için iç işleyişini mutlaka anlamak gerekir
• Kayıt defterinin özü, içeriğe göre adreslenen (content-addressable) blob deposudur; tüm katmanlar, yapılandırma dosyaları ve artifact'ler digest'i adres olarak kullanarak saklanır
• İmaj push işlemi, blob'ların yüklenmesinden sonra bunların manifest ile bir araya getirilmesi sırasıyla ilerler; pull ise önce manifest'in alınması, ardından blob'ların sırayla indirilmesi şeklindeki ters yapıdır
• İmaj silme, yalnızca untag işlemiyle tamamen gerçekleşmez; başka manifest'lerde paylaşılan katmanlar önce kontrol edilmeli, ardından blob'lar da doğrudan silinmelidir
• Çok platformlu imajlar, mevcut API endpoint'lerini koruyup yalnızca image index (manifest list) adlı ek bir dolaylı katman eklenerek uygulanır

---

Registry API'ye genel bakış

• Modern konteyner kayıt defterlerinin çoğu OCI Distribution Specification uygular; bu spesifikasyon, içerik dağıtımını standartlaştıran bir API protokolü tanımlar
• Registry API pratikte sade ve anlaşılması kolaydır; yalnızca curl ile bile doğrudan yeterince kontrol edilebilir

Blob yükleme ve indirme

• Kayıt defteri özünde içeriğe göre adreslenen bir blob deposudur; dosya yerelde hash'lenir, ardından digest adres olarak kullanılarak yüklenir
• En basit yükleme yöntemi Monolithic PUT yaklaşımıdır; POST ile oturum başlatılır, ardından PUT ile blob gönderilir; yani 2 aşamalı bir yapıdır
  • Büyük dosyalarda POST + PATCH + PUT parça parça yükleme yöntemi daha verimlidir; ancak küçük blob'lar için Monolithic PUT yeterlidir
• Yükleme başarılı olduğunda HTTP/2 201 Created yanıtıyla birlikte yeni blob'un konumunu gösteren Location header'ı döner
• İndirme ise yalnızca digest biliniyorsa GET /v2/<repo>/blobs/<digest> ile doğrudan yapılabilir

İmaj Push

• İmaj push süreci: (1) her rootfs katmanı blob'unun yüklenmesi → (2) image configuration blob'unun yüklenmesi → (3) tüm digest'leri tek bir JSON belgesinde birleştiren manifest dosyasının push edilmesi
• Manifest, PUT /v2/<repo>/manifests/<tag> endpoint'ine yüklenir ve etiket bu aşamada oluşturulur
• Gerçek istemciler (ör. docker push) blob yüklemelerini paralel yürütür; ancak mantığı anlamak için sıralı işleme de mümkündür
• İmaj dizini örneği: config.json, layer-1.tar.gz, layer-2.tar.gz, manifest.json

Etiket listesini görüntüleme

• GET /v2/<repo>/tags/list endpoint'iyle belirli bir repository içindeki tüm etiketlerin listesi alınabilir
• Bu özellik docker CLI'da görünmez; yalnızca curl veya crane, regctl gibi araçlarla erişilebilir
  • crane ve regctl, aynı endpoint'i ls komutuyla sarmalayan araçlardır

İmaj Pull

• Pull süreci push'ın tersidir: (1) GET /v2/<repo>/manifests/<tag> ile manifest alınır → (2) manifest'te belirtilen digest'lere göre tüm blob'lar indirilir
• Modern manifest'ler, rootfs katmanları ve imaj yapılandırmasının yanı sıra Helm chart'ları, SBOM, provenance attestation ve LLM ağırlıkları gibi keyfi artifact'lere blob olarak referans veren genel amaçlı bir depo olarak da kullanılır

İmaj silme

• İmaj silme basit değildir; yalnızca etiketin kaldırılması (untag), manifest'in kendisinin silindiği anlamına gelmez
• Tam silme süreci:
  • (1) DELETE /v2/<repo>/manifests/<tag> ile etiketin kaldırılması
  • (2) manifest'in digest ile alınarak referans verdiği tüm blob'ların kontrol edilmesi
  • (3) yalnızca başka manifest'ler tarafından paylaşılmayan blob'ların seçerek silinmesi
  • (4) DELETE /v2/<repo>/blobs/<manifest-digest> ile manifest blob'unun silinmesi
• Kayıt defteri içeriğe göre adreslenen bir depo olduğundan, aynı rootfs katmanı birden fazla imaj tarafından paylaşılabilir; bu nedenle silme işlemi o katmana referans veren tüm imajları etkileyebilir
• Alternatif olarak tüm etiketler kaldırıldıktan sonra kayıt defterinin garbage collection ayarına güvenilebilir; ancak ortak kullanılan kayıt defterlerinde bu her zaman etkin değildir

Çok platformlu imajlar

• Çok platformlu imajlar Registry API yapısı değiştirilmeden uygulanır — endpoint ekleme veya değiştirme olmadan mevcut API aynen kullanılır
• Yapılandırma şekli:
  • Her tekil platform varyantı (amd64, arm64 vb.) ayrı bir manifest ile birlikte önce digest tabanlı olarak push edilir
  • Ardından image index (manifest list) adı verilen üst düzey manifest, etiketle birlikte push edilir
• GET /v2/<repo>/manifests/<tag> çağrısı yapıldığında tek platformlu manifest veya image index'ten biri döner; çağıran taraf bunu dönen belgenin content type'ına göre ayırt etmelidir
• Sonuç olarak çok platform desteği, mevcut yapıya yalnızca bir dolaylı katman ve bir index belgesi yükleme/indirme adımı ekler

Registry API'yi koruma

• OCI Distribution Spec kimlik doğrulama yöntemini katı biçimde tanımlamaz; ancak gerçek dünyadaki kayıt defterlerinin çoğu HTTP Basic kimlik doğrulaması kullanır
• Kimlik bilgilerinin düz metin olarak iletilmesini önlemek için mutlaka HTTPS üzerinde çalıştırılmalıdır