Unregistry – “docker push” ile registry olmadan doğrudan sunucuya aktarım

• Unregistry, Docker daemon deposundaki imajları doğrudan depolayıp sunan hafif bir container imaj registry’sidir ve docker pussh komutuyla imajları uzak Docker sunucusuna SSH üzerinden doğrudan aktarır
• Mevcut seçenekler Docker Hub/GitHub Container Registry, self-hosted registry, docker save | ssh... docker load ve uzakta yeniden build etmektir; ancak bunların her birinde sırasıyla herkese açık veya ücretli depo, operasyon yükü, tüm imajın aktarılması ve sunucu kaynaklarının boşa harcanması gibi sorunlar vardır
• docker pussh myapp:latest user@server, bir SSH tüneli kurar, uzak sunucuda geçici bir unregistry container başlatır ve ardından yönlendirilen localhost portu üzerinden docker push çalıştırarak yalnızca uzakta olmayan katmanları aktarır
• Uzak sunucuda Docker çalışma ortamı, docker komutu yetkisi ve ilk çalıştırmada ghcr.io/psviderski/unregistry:latest erişimi gerekir; ayrıca unregistry container’ı /run/containerd/containerd.sock erişimi nedeniyle root olarak çalışır
• Docker’ın containerd image store özelliği etkinleştirilirse aktarılan imajlar Docker’da hemen kullanılabilir ve çift depolama önlenir; ancak mevcut classic storage driver ile oluşturulmuş imajlar ve container’lar geçici olarak görünmeyebilir

---

Unregistry’nin çözdüğü dağıtım sorunu

• Unregistry, harici bir registry olmadan Docker imajlarını uzak sunucuya taşımak için hafif bir container imaj registry’sidir
• İçerdiği Docker CLI eklenti komutu docker pussh olup, addaki ek s harfi SSH anlamına gelir
• Yerelde oluşturulan Docker imajlarını sunucuya taşırken yaygın seçeneklerin kısıtları şunlardır
  • Docker Hub / GitHub Container Registry: Kodun herkese açık olması gerekir ya da private depo maliyeti oluşur
  • Self-hosted registry: Bakım, güvenlik ve depolama maliyeti gerektiren ayrı bir servis oluşur
  • Save/Load: docker save | ssh <remote server> docker load, sunucuda zaten %90 mevcut olsa bile tüm imajı aktarır
  • Remote rebuild: Zaman ve sunucu kaynağı tüketir; ayrıca production ortamında build hatalarının nedenini debug etmek gerekebilir

docker pussh nasıl çalışır

• Temel kullanım aşağıdaki tek satırdır

docker pussh myapp:latest user@server

• Bu komut, registry yapılandırması, abonelik, ara depo veya açık port gerektirmeden yalnızca eksik katmanları SSH üzerinden doğrudan aktarır
• İç işleyiş şu sırayla ilerler
  • Uzak sunucuya bir SSH tüneli oluşturur
  • Sunucuda geçici bir unregistry container’ı başlatır
  • Rastgele bir localhost portunu tünel üzerinden unregistry portuna yönlendirir
  • Yönlendirilen port üzerinden docker push çalıştırarak yalnızca uzakta olmayan katmanları aktarır
  • Aktarılan imajlar uzak Docker daemon’unda hemen kullanılabilir hale gelir
  • unregistry container’ını durdurur ve SSH tünelini kapatır
• Proje, Docker imajları için rsync benzeri basit ve verimli bir aktarım yöntemi sunmayı hedefler
• Unregistry, birden çok Docker host’una container dağıtmak için geliştirilen hafif araç Uncloud için oluşturuldu; tam bir registry’den daha basit ve save/load yönteminden daha verimli bir çözüme ihtiyaç vardı

Çalışma gereksinimleri ve kısıtlar

• Yerel makinede Docker CLI eklenti desteği gerekir; Docker 19.03 veya üzeri ve OpenSSH istemcisi gereklidir
• Uzak sunucuda Docker kurulu ve çalışıyor olmalıdır
• SSH kullanıcısının docker komutunu çalıştırma yetkisi olmalıdır
  • Kullanıcı ya root olmalı ya da root olmayan kullanıcı docker grubunda yer almalıdır
  • İlgili belgeler için Docker’ın Manage Docker as a non-root user sayfasına bakılabilir
  • sudo gerekiyorsa parola istemeden sudo docker çalıştırabilmelidir
• İlk docker pussh çalıştırmasında uzak sunucu ghcr.io üzerinden ghcr.io/psviderski/unregistry:latest imajını çekebilmelidir
  • Proxy gereken sunucular, Docker’ın Daemon proxy configuration kılavuzuna göre yapılandırılmalıdır
  • Air-gapped ortamlarda veya ghcr.io erişimi kısıtlı ortamlarda, gereken unregistry imaj sürümü kontrol edilip elle preload yapılabilir
• unregistry container’ı /run/containerd/containerd.sock yoluna erişmek zorunda olduğundan, gerekli yetkiler için root olarak çalıştırılır

Kurulum ve desteklenen platformlar

• macOS/Linux üzerinde docker-pussh, Homebrew ile kurulabilir

brew install psviderski/tap/docker-pussh

• Homebrew kurulumundan sonra docker pussh komutunu Docker CLI eklentisi olarak kullanabilmek için ~/.docker/cli-plugins/docker-pussh sembolik bağlantısı oluşturulmalıdır
• macOS/Linux için doğrudan indirme yöntemi de sunulur
  • Güncel sürüm örneği olarak v0.4.3 içindeki docker-pussh betiğinin Docker eklenti dizinine indirilip çalıştırma izni verilmesi yöntemi bulunur
  • main branch’teki en güncel betiği indirme seçeneği de sunulur
• Debian, @dariogriffo tarafından oluşturulan ve bakımı yapılan gayriresmî paket deposu unregistry-debian üzerinden kurulabilir
• Windows şu anda desteklenmiyor; ancak WSL 2 ve Linux kurulum adımları denenebilir
• Kurulum doğrulaması şu komutla yapılır

docker pussh --help

containerd image store ayarı

• Unregistry, Docker’ın kullandığı alt container runtime olan containerd’nin image store’una imajları doğrudan yazar
• Varsayılan Docker davranışında Docker ayrı bir depolama katmanı tutar ve containerd imajlarını doğrudan kullanmaz
• Docker’da containerd image store etkinleştirilirse, Docker unregistry’nin kaydettiği imajları doğrudan kullanabilir ve yinelenen depolamayı ortadan kaldırır

• containerd image store etkinleştirildiğinde

  • unregistry ile push edilen imajlar Docker’da hemen kullanılabilir
  • İmajlar containerd’de yalnızca bir kez depolanır ve ek depolama alanı kullanılmaz
  • unregistry’den classic Docker image store’a ek docker pull adımı gerekmediği için pussh işlemi daha hızlı olur

• Varsayılan Docker davranışı korunduğunda

  • Push sonrasında pussh, uzak host’ta ek bir docker pull çalıştırarak imajı Docker’da kullanılabilir hale getirir
  • İmajlar hem containerd’de hem de classic Docker image store’da tutulur; yani iki kez depolanır
  • containerd içindeki unmanaged imajlar zamanla disk alanını doldurabilir
  • Elle yönetim şu komutlarla yapılabilir

  sudo ctr -n moby images ls
  sudo ctr -n moby images rm <image>
  

• Ayar sırasında dikkat edilmesi gerekenler

  • Docker Engine’de containerd image store’u etkinleştirme yöntemi için resmî Docker belgeleri izlenmelidir
  • containerd image store’a geçildiğinde classic storage driver ile oluşturulmuş imajlar ve container’lar geçici olarak görünmez olabilir
  • Bu kaynaklar dosya sisteminde kalır ve containerd image store özelliği kapatıldığında yeniden erişilebilir hale gelir

Kullanım örnekleri

• Temel aktarımda yalnızca imaj adı ve uzak SSH hedefi belirtilir

docker pussh myapp:latest [e-mail]

• SSH agent içine private key yüklenmemişse -i ile anahtar belirtilebilir

docker pussh myapp:latest ubuntu@192.168.1.100 -i ~/.ssh/id_rsa

• Özel SSH portu, hedefin sonuna port eklenerek verilir

docker pussh myapp:latest user@server:2222

• Özel SSH config dosyası -F ile belirtilebilir

docker pussh myapp:latest prod-server -F ~/.ssh/config.prod

• Multi-platform imajlarda yalnızca belirli bir platformu push etmek için --platform kullanılır
  • Yerel Docker’ın multi-platform imajları desteklemesi için containerd image store kullanılmalıdır

docker pussh myapp:latest user@server --platform linux/amd64

• Uzak host’ta belirli bir unregistry imaj sürümünü kullanmak için UNREGISTRY_IMAGE ortam değişkeni belirtilebilir

UNREGISTRY_IMAGE=ghcr.io/psviderski/unregistry:A.B.C docker pussh myapp:latest [e-mail]

Öne çıkan kullanım senaryoları

• Production sunucu dağıtımında, yerelde build edilen imajlar ara bir registry olmadan doğrudan sunucuya push edilip çalıştırılabilir

docker build --platform linux/amd64 -t myapp:1.2.3 .
docker pussh myapp:1.2.3 deploy@prod-server
ssh deploy@prod-server docker run -d myapp:1.2.3

• CI/CD pipeline’larında registry karmaşıklığı atlanarak imajlar doğrudan dağıtım hedefine gönderilebilir

- name: Build and deploy
  run: |
    docker build -t myapp:${{ github.sha }} .
    docker pussh myapp:${{ github.sha }} deploy@staging-server

• Homelab ve air-gapped ortamlarda, herkese açık registry’lere internet üzerinden erişemeyen izole ağlarda imaj dağıtımı yapılabilir

Gelişmiş kullanım ve ilgili projeler

• Unregistry, bağımsız çalışan yerel bir registry olarak da kullanılabilir
  • /run/containerd/containerd.sock mount edilerek ghcr.io/psviderski/unregistry container’ı çalıştırılır
  • Sonrasında localhost:5000, normal bir registry gibi docker tag ve docker push ile kullanılabilir
• SSH yapılandırması için standart SSH config dosyaları kullanılabilir veya -F ile ayrı bir config dosyası verilebilir
• İlgili üçüncü taraf projeler de sunuluyor
  • https://github.com/SonOfBytes/unregistry-action: docker-pussh Docker CLI eklentisiyle Docker imajlarını uzak sunucuya push eden GitHub Action
  • https://github.com/RezaKargar/setup-unregistry: docker-pussh Docker CLI eklentisini kuran GitHub Action
  • https://github.com/iloveitaly/docker-image-cleanup: self-hosted registry’de eski Docker imajlarını kaldırırken son imajları ve kullanımda olan imajları koruyan Python aracı
• Uygulamada Spegel ve Docker Distribution anılıyor
  • Spegel, containerd image store’u backend olarak kullanan registry uygulamasına ilham veren bir P2P container imaj registry’sidir
  • Docker Distribution ise unregistry’nin temelini oluşturan Docker registry uygulamasıdır

[GN⁺]

Hacker News yorumları

• Docker’ı yapan biri olarak hoşuma gitti. İdeal tasarımın, Docker motoru ile registry arasında ayrım olmayan tek bir sunucu olacağını düşünüyorum.
  Gerektiğinde container’ları saklayabilen, aktarabilen ve çalıştırabilen bir yapı olsaydı çok daha sağlam bir bileşen olurdu; ayrıca motor ile registry’nin imajları saklama biçimlerinin farklılaşması gibi talihsiz bir gidişat da önlenebilirdi.
  Ayrıca her production cluster’da dağıtık bir imaj deposu olması gerektiğini ve bu depoya imaj push etmenin deployment’ı tetiklemesi gerektiğini düşünüyorum. Bugünkü gibi registry’ye push edip, cluster’ı yapılandırıp, her node’un registry’den pull etmesi kırılgan ve verimsiz. Daha iyi bir tasarımı savundum ama atalet çok büyüktü; erken dönem Kubernetes topluluğu da Docker’dan çıkan fikirlere düşmanca yaklaşıyordu.

  • İmajlar için en az üç farklı dosya sistemi yerleşimi, motorun içinde de iki ayrı imaj deposu olması gerçekten dağınık. Yine de Docker’ın mevcut modeli bozmadan bu yöne ulaşması için hâlâ çok geç olmadığını düşünüyorum. Tabii Docker’ın bunu umursayıp umursamayacağını bilmiyorum; son zamanlarda zor bir dönemden geçiyor gibi.
    Cluster’a push ederek deployment akıllıca görünüyor. Tüm node’lara unregistry koyup birbirlerinden imaj almalarını ve paylaşmalarını sağlayan dağıtık bir imaj deposu fikrini düşünüyorum, ama push’un deployment’ı tetiklemesi konusunu biraz daha değerlendirmek gerek.

• Güzel. pussh komutu gerçekten zarif bir kelime oyunu olarak takdiri hak ediyor. Hatırlaması kolay, anlamı hemen belli oluyor ve kardeş standart komuttan sadece bir harf farklı.

  • Kötü değil ama docker push-over-ssh gibi daha resmî bir alias da olsa iyi olurdu.
    İş birliğiyle geliştirilen otomasyonlarda pussh, işlevi bilmeyen birine yazım hatası gibi görünüp gereksiz kafa karışıklığı yaratabilir. Buna karşılık push-over-ssh bunun kasıtlı bir ad olduğunu açıkça gösteriyor. Kısa seçenek ve uzun seçenek gibi düşünülebilir.
  • Eklenen s, sssh içindeki s.
    “Şu fazladan s ne?”
    “Yazım hatası.”
  • Çakışmaya da çok müsait.

• 2015’te bu özelliği safça Docker ana dalına eklemek için bir PR[1] göndermiştim; kısa süre sonra başka alanlara yardım etmeye yönlendirildim. Registry kullanmayı gereksiz kılmak Docker’ın iş modelini fazla sarsmış olabilir.
  [1]: https://github.com/richardcrichardc/docker2docker

  • Demek öncüsü sizmişsiniz. Docker’da hâlâ imaj katmanlarını gezmeye yarayan bir API olmaması üzücü.
    Sonunda varsayılanı containerd imaj deposuna geçirme planları olduğunu düşünüyorum. Hem yerelde hem uzakta containerd imaj deposu kullanılınca, registry wrapper’ı olmadan da başlangıçta yaptığınız şeyi yapabilmek mümkün olacak gibi.

• Ansible gibi push tabanlı deployment araçları zaten kullanan sistemlerle iyi uyacak harika bir fikir. Docker registry için 7/24 destek olmayan şirketlerde iyi bir hotfix deployment mekanizması olarak da kullanılabilir gibi görünüyor.
  buildah gibi OCI araçlarıyla temiz biçimde entegre olup olmadığını, yoksa iki uçta da tam bir Docker kurulumuna mı ihtiyaç duyduğunu merak ediyorum. Henüz derinlemesine bakmadım ama böyle bir kurulumda skopeo’nun çalışması için eksik parça, uzak sunucuda mini bir registry’yi bootstrap etmek gibi görünüyor.

  • Uzak tarafta containerd gerekiyor. Docker ve Kubernetes de containerd kullanıyor. İstemci tarafında registry API’sini, yani OCI Distribution spesifikasyonunu (https://github.com/opencontainers/distribution-spec) konuşan herhangi bir araç yeterli.
    Unregistry, API katmanında resmî Docker registry kodunu yeniden kullandığı için https://hub.docker.com/_/registry gibi görünür ve davranır.
    İstemcide skopeo, crane, regclient, BuildKit gibi OCI registry konuşan araçları kullanabilirsiniz. Ancak bunları kullanmak için uzak host’ta unregistry’yi elle çalıştırmanız gerekir. docker pussh komutu sadece yerel Docker’ı kullanarak bu akışı otomatikleştirir.
    Basitçe bir Bash script’i gibi düşünebilirsiniz: https://github.com/psviderski/unregistry/blob/main/docker-pu...
    İstediğiniz şekilde kolayca değiştirebilirsiniz.
  • Katılıyorum. Yönettiğim birkaç serviste imajları yerelde build edip kaydediyor, Ansible ile arşivi upload ediyor, sonra imajı geri yüklüyorum; genelde istediğimden çok daha uzun sürüyor.
  • İki uçta da Docker daemon gerekiyor. SSH üzerinden iki daemon arasında katmanları paylaşmanın akıllıca bir yolu.

• Başından beri böyle olmalıydı. Harika.
  Docker registry’nin de kullanılacağı yerler var ama genel olarak fazla tasarlanmış ve hacker ruhunun karşı tarafında duruyor.

  • Girişim sermayesi almış bir şirketti; Docker’ın da bir şekilde para kazanması gerekiyordu.
  • GitHub Actions ile birlikte GitHub’ın registry’si olan ghcr.io’yu kullanmanızı öneririm.
    Private ghcr.io registry’ye imaj build edip push eden bir .yaml workflow’u ayarlamak 20 dakika, sunucunun oradan imaj çekmesine izin vermek de yaklaşık 5 dakika sürdü. Oldukça pratik bir kurulum.
  • Karmaşıklık registry’ye blob push etme prosedüründe gibi görünüyor. Daha önce OCI uyumlu salt okunur bir registry yapmıştım; o kadar karmaşık değildi.

• GitLab’da imajı build edip Artifactory’ye push eden, ardından deployment tetiklenip Artifactory’den çekerek AWS ECR’ye tekrar push eden, EKS’teki deployment template’ini güncelleyince ECR’den node’lara çekip Pod container’ını ayağa kaldıran bir pipeline’a bakıyorum.
  Hayatımda buna ihtiyacım var.

  • Meraktan soruyorum: Artifactory ve ECR’yi ikisini birden kullanmanızın nedeni ne? Biz maliyet düşürmek için Artifactory’den ECR’ye geçmeyi değerlendiriyoruz.
  • Son projemdeki pipeline’da container pull ve push için geçen süre, gerçek uygulama build’inden daha uzundu. Üstelik tüm bu süre, health check bekleme süresinin yanında bile küçüktü; oysa gerçekte sağlıklı olup olmadığı, başladıktan 1 saniye bile geçmeden anlaşılabiliyordu.

• Bunu görünce uncloud’dan haberdar oldum. Yan proje sunucu kurulumu için dokku gibi ama biraz daha güçlü bir şey arıyordum; tam da öyle bir his veriyor.

  • https://skateco.github.io/ da var. Kabaca bakınca benzer görünüyor.
  • Portainer’ı kullanmadıysanız ya da değerlendirmediyseniz öneririm. AWS’te iki EC2 instance üzerinde Portainer Community Edition ve Portainer Agent çalıştırıyorum; gayet iyi çalışıyor.
    Stack özelliği de gerçekten iyi; aslında Docker Compose gibi. Bir EC2 instance’ında Portainer Agent, konteyner içindeki Caddy’yi çalıştırıyor; Caddy de yük dengeleyici ve reverse proxy görevi görüyor.
  • uncloud fikrinin size anlamlı gelmesine sevindim. Sorularınız olursa veya yardıma ihtiyaç duyarsanız Discord’a katılabilirsiniz.

• Docker’ın en başından beri böyle çalışmıyor olması oldukça garip. Harika görünüyor.

  • Zaten imajı bir arşiv haline getirip sunucuya push ederek, ardından sunucuda o arşivden çalıştırarak aynı şeyi yapabilirsiniz.
    Arşive kaydetme docker save -o may-app.tar my-app:latest gibi, yükleme ise docker load -i /path/to/my-app.tar gibi yapılır.
    Ansible gibi araçlar kullanırsanız “Unregistry”nin otomatikleştirdiği işi kolayca başarabilirsiniz. GitHub deposuna göre save/load yönteminin dezavantajı tüm imajı ağ üzerinden aktarması; bu da gerçekten sorun olabilir. Arşiv dosyası yerine imajın kendisini yönetmek de daha kullanışlı görünüyor.

• Temiz bir proje ve yaklaşım. Pahalı registry’lerden bıkıp Zot[1]’u kendim host etmeye başladım, ama bazı kullanım alanları için bu çok daha kolay görünüyor.
  Kolayca kurulabilen, ucuz ve kullanım bazlı ücretlendirilen özel registry hizmeti olsa iyi olur diye düşünen başka biri var mı merak ediyorum.
  [1]: https://zotregistry.dev

  • Haberiniz yoksa zothub.io’nun SSL sertifikasının süresi dolmuş.

• İyi bir fikir. Yine de dağıtımın servise bağlanması gibi bir dezavantaj olabilir. Örneğin scale-out ya da red/green dağıtımın nasıl yapılacağını bilmiyorum; bu işleri yapan tarafın push’tan haberdar olması gerekecek gibi.
  Düzeltme: Bunu yapan şey uncloud’muş. Az önce öğrendim.
  Yine de bu bir trade-off. Ölçek küçükse, tek bir Hetzner VM kullanıyorsanız, sadelikten memnunsanız ve imajı yerelde build etmek sizin için sorun değilse harika.

  • Kesinlikle her zaman bir trade-off var. Seçeneklerin olması ve her iş için en uygun aracı seçebilmek güzel.