Harbor ile Özel Konteyner Registry

Basit bir registry:2 kurulumu, tek ekiple çalışan bir yerde uzun süre yeter. Ama ikinci ekip geldiğinde ilk soru şu olur: "Onlar bizim imajlarımızı görebiliyor mu?" Cevap evettir, çünkü temel registry'de htpasswd ile giriş yapan herkes her depoya erişir. Ardından ikinci soru gelir: bu imajın içindeki OpenSSL sürümünde bilinen bir açık var mı? Üçüncüsü: geçen ay silmemiz gereken 400 eski etiketi kim temizleyecek? Bu üç soru, temel registry'nin sınırının nerede bittiğini gösterir.

Harbor tam olarak bu boşluğu doldurmak için tasarlanmış, CNCF çatısı altında olgunlaşmış açık kaynaklı bir konteyner registry'sidir. Proje bazlı yetkilendirme, beş kademeli roller, süreli robot hesapları, Trivy ile otomatik zafiyet taraması, zafiyetli imajın çekilmesini engelleyen dağıtım politikası, etiket saklama kuralları, proje kotaları ve başka bir registry'ye çoğaltma özelliklerini tek arayüzde toplar. Bu rehberde Harbor'ı sıfırdan kuracağız, projeleri ve rolleri ayarlayacağız, tarama ile dağıtım politikasını devreye alacağız, saklama kuralı yazacağız ve yedekleme ile yükseltme sürecine bakacağız.

Harbor Ne Zaman Gerekir#

Harbor bir registry:2 kurulumunun üzerine kurulur ve onun yerine geçer; ama her durumda gerekli değildir. Karar vermenizi kolaylaştıracak karşılaştırma şudur:

Kabaca kural şu: tek ekip, bir avuç imaj ve kimseyle paylaşılmayan bir sunucu varsa kendi Docker registry kurulumu yazısındaki temel kurulum yeterlidir. Birden fazla ekip, dış paydaş, uyum gereksinimi ya da "hangi imajda hangi açık var" sorusuna cevap verme zorunluluğu varsa Harbor'ın getirdiği ek karmaşıklık kendini fazlasıyla ödetir.

Donanım ve Ön Gereksinimler#

Harbor tek bir konteyner değildir; çekirdek servis, portal, registry, iş servisi, Redis ve PostgreSQL'den oluşan bir Compose yığını olarak çalışır. Dolayısıyla kaynak ihtiyacı temel registry'den belirgin şekilde yüksektir.

Asgari sayılan yapılandırma iki çekirdek, 4 GB RAM ve 40 GB disktir; gerçek kullanımda Trivy taraması da açıkken dört çekirdek ve 8 GB RAM çok daha rahat çalışır. Disk tarafını cömert planlayın: imaj deposu, PostgreSQL verisi ve Trivy'nin zafiyet veritabanı aynı diskte durur.

Kurulumdan önce üç şeyi hazırlayın:

1. Bir alan adı ve ona işaret eden A kaydı, örneğin harbor.firmaniz.com.
2. Geçerli bir TLS sertifikası (Let's Encrypt yeterlidir).
3. Docker ve Docker Compose eklentisi kurulu, güncel bir Linux sunucu.

# Sertifikayi Harbor kurulumundan ONCE alin
sudo certbot certonly --standalone -d harbor.firmaniz.com

# Docker Compose eklentisi var mi
docker compose version

Sertifikayı önceden almanızı öneriyorum çünkü Harbor kendi nginx'ini 443 portunda çalıştırır ve kurulum sonrası --standalone doğrulama yapmak port çakışması yaratır.

Kurulum Adım Adım#

Harbor, GitHub sürüm sayfasından indirilen bir kurulum paketiyle gelir. Çevrimdışı (offline) paket tüm imajları içerir ve internet erişimi kısıtlı ortamlarda tercih edilir; çevrimiçi paket daha küçüktür ve imajları kurulum sırasında çeker.

cd /opt
# Surum numarasini resmi surum sayfasindan alin
sudo tar xzf harbor-offline-installer-vX.Y.Z.tgz
cd harbor

# Sablonu kopyalayip duzenleyin
sudo cp harbor.yml.tmpl harbor.yml
sudo nano harbor.yml

harbor.yml içinde değiştirmeniz gereken alanlar şunlardır:

hostname: harbor.firmaniz.com

https:
  port: 443
  certificate: /etc/letsencrypt/live/harbor.firmaniz.com/fullchain.pem
  private_key: /etc/letsencrypt/live/harbor.firmaniz.com/privkey.pem

# Ilk giristen sonra arayuzden mutlaka degistirin
harbor_admin_password: ilk-kurulum-parolasi

database:
  password: guclu-bir-db-parolasi

data_volume: /data/harbor

Ardından hazırlık ve kurulum betiklerini çalıştırırsınız. Trivy tarayıcısını kurulum anında etkinleştirmek, sonradan eklemekten çok daha kolaydır:

sudo ./prepare
sudo ./install.sh --with-trivy

# Servisler ayakta mi
sudo docker compose ps

Kurulum bittiğinde https://harbor.firmaniz.com adresine admin kullanıcısı ve harbor.yml içinde verdiğiniz parolayla giriş yaparsınız. İlk iş o parolayı arayüzden değiştirmek ve harbor.yml dosyasının izinlerini kısmak olmalıdır; dosya veritabanı parolasını da düz metin içerir.

sudo chmod 600 /opt/harbor/harbor.yml

Proje, Rol ve Robot Hesapları#

Harbor'da imajlar proje altında toplanır ve imaj yolu harbor.firmaniz.com/proje/imaj:etiket biçimindedir. Proje ya herkese açık (public) ya da özeldir; özel projede yalnızca üye olanlar çekebilir.

Beş rol vardır ve yetkileri kademelidir: sınırlı misafir yalnızca kendi çektiğini görür, misafir salt okunur erişir, geliştirici çekme ve gönderme yapabilir, sürdürücü ayrıca tarama başlatıp etiket silebilir, proje yöneticisi ise üye ve politika yönetir. Bir kişiye verdiğiniz rolü daima en dar olandan seçin; ihtiyaç doğduğunda yükseltmek kolaydır.

Otomasyon için asıl kullanmanız gereken şey robot hesaplarıdır. Robot hesabı bir kişiye değil bir sisteme aittir, yalnızca seçtiğiniz izinlere sahiptir ve son kullanma tarihi vardır. CI hattınıza kendi kullanıcı parolanızı vermek yerine, yalnızca ilgili projeye gönderme yetkisi olan bir robot hesabı üretin:

# CI hattinda: robot hesabiyla giris
docker login harbor.firmaniz.com \
  -u 'robot$firmaniz+ci' \
  -p "$HARBOR_ROBOT_TOKEN"

docker tag firmaniz/web:1.4.0 harbor.firmaniz.com/firmaniz/web:1.4.0
docker push harbor.firmaniz.com/firmaniz/web:1.4.0

Üretim sunucularınıza ise yalnızca çekme yetkisi olan ayrı bir robot hesabı verin. Böylece bir sunucu ele geçirilse bile registry'ye zararlı imaj gönderilemez. Robot token'larını sunucuda düz dosyada tutmayın; gizli bilgi saklamanın doğru yolları için Docker'da gizli bilgi yönetimi yazısına bakabilirsiniz.

Zafiyet Taraması ve Dağıtım Politikası#

Trivy etkinken Harbor, gönderilen her imajın katmanlarındaki paketleri bilinen zafiyet veritabanıyla karşılaştırır ve sonucu kritik, yüksek, orta, düşük olarak sınıflandırır. Taramayı elle başlatabilir ya da proje ayarlarından "gönderildiğinde otomatik tara" seçeneğini açabilirsiniz.

Asıl değerli özellik taramanın kendisi değil, sonucuna göre davranmaktır. Proje ayarlarındaki dağıtım güvenliği seçeneğiyle, belirlediğiniz önem derecesinin üzerinde zafiyet içeren imajların çekilmesini engelleyebilirsiniz. Bu, tarama raporunu okumayı unutsanız bile zafiyetli imajın üretime gitmesini yapısal olarak durdurur.

Politikayı devreye alırken iki pratik uyarı: birincisi, eşiği en baştan "kritik" seviyesinde tutun; "yüksek" ile başlarsanız neredeyse her imaj engellenir ve ekip politikayı kapatır. İkincisi, düzeltmesi yayınlanmamış zafiyetleri hariç tutma seçeneğini kullanın; yamalanamayan bir açık yüzünden dağıtımı durdurmanın kimseye faydası yoktur.

Tarama sonuçlarını iyileştirmenin en etkili yolu imajı küçültmektir. İmajda ne kadar az paket varsa taranacak yüzey de o kadar küçüktür; ince temel imajlara geçmenin yolları için Docker imaj boyutu optimizasyonu yazısı doğrudan işinize yarar.

Etiket Saklama Politikaları ve Kota#

Registry disklerini dolduran şey nadiren büyük imajlardır; genellikle CI hattının her commit'te ürettiği yüzlerce etikettir. Harbor bunu politika ile çözer: proje bazında "her depoda en son 10 etiketi tut" ya da "90 günden eski etiketleri sil" gibi kurallar tanımlar, zamanlanmış olarak çalıştırırsınız.

Saklama kuralı yazarken bir güvenlik ağı bırakın. Üretimde çalışan bir sürümün etiketi yanlışlıkla silinirse geri dönüş yapamazsınız. Pratik desen şudur: sürüm etiketlerini (1.4.0 gibi) koruyacak bir kural, geçici etiketleri (main-abc1234 gibi) temizleyecek ayrı bir kural yazın. Kritik sürümler için değişmez etiket (immutable tag) kuralı tanımlayarak o etiketlerin üzerine yazılmasını da engelleyebilirsiniz.

Kota tarafı da benzer şekilde proje bazlıdır: her projeye bir depolama sınırı verirsiniz ve sınır dolduğunda gönderme reddedilir. Bu, tek bir ekibin tüm diski tüketip diğerlerinin dağıtımını durdurmasını engeller. Saklama kuralları etiketleri işaretler, gerçek disk alanı ise arayüzden zamanlanan çöp toplama işiyle geri alınır; ikisini birlikte planlamazsanız disk boşalmaz.

Çoğaltma ile Yedek Registry#

Harbor'ın çoğaltma kuralları, imajları başka bir registry'ye otomatik olarak kopyalar. İki yönde çalışır: gönderme tabanlı kural, kendi Harbor'ınızdaki imajları hedefe iter; çekme tabanlı kural, uzak bir kaynaktan imajları içeri alır.

En sık kullanılan üç senaryo şunlardır. Birincisi felaket kurtarma: ikinci bir lokasyondaki Harbor'a sürekli çoğaltarak ana registry düştüğünde dağıtıma devam edebilirsiniz. İkincisi ortam ayrımı: hazırlık ortamında test edilip onaylanan imajları üretim registry'sine ayrı bir kuralla taşırsınız. Üçüncüsü dışarıdan içeri alma: sık kullandığınız genel imajları kendi Harbor'ınıza çekerek dış bağımlılığı ve çekme limitlerini ortadan kaldırırsınız.

Kural tanımlarken filtreleri dar tutun. Depo adı, etiket deseni ve kaynak türü filtrelerini kullanmadan yazılan bir kural, ilk çalıştığında yüzlerce gigabaytı hedefe taşımaya kalkar ve hattı tıkar. Ayrıca ilk senkronizasyonu düşük trafikli bir saatte, elle tetikleyerek başlatın.

Yedekleme ve Yükseltme#

Harbor'da yedeklenmesi gereken üç şey vardır ve üçü birlikte alınmalıdır: PostgreSQL veritabanı (proje, kullanıcı, politika ve tarama verisi), data_volume altındaki imaj deposu ve harbor.yml yapılandırma dosyası. Sadece imaj deposunu yedeklemek yetmez; veritabanı olmadan o imajların kime ait olduğu bilinmez.

cd /opt/harbor
# 1) Servisleri durdur - tutarli yedek icin
sudo docker compose down

# 2) Veri ve yapilandirmayi arsivle
sudo tar czf /yedek/harbor-data-$(date +%F).tar.gz /data/harbor
sudo cp harbor.yml /yedek/harbor.yml-$(date +%F)

# 3) Geri baslat
sudo docker compose up -d

Yükseltme sırası da benzerdir: önce yedek alın, servisleri durdurun, yeni sürüm paketini indirin, resmi geçiş aracıyla harbor.yml dosyanızı yeni biçime taşıyın ve ./prepare ile ./install.sh adımlarını tekrarlayın. Sürüm atlamayın; Harbor'ın belgelediği yükseltme yolunu adım adım izleyin, iki büyük sürüm birden atlamak veritabanı geçişini bozabilir.

Sık Yapılan Hatalar#

Sertifikayı 443 portu doluyken almaya çalışmak. Harbor kendi nginx'ini 443'te çalıştırır; certbot --standalone bu portu isteyince çakışır. Sertifikayı kurulumdan önce alın, yenileme için de --webroot ya da DNS doğrulaması kullanın ve yenileme sonrası Harbor'ı yeniden başlatan bir kanca ekleyin.

harbor.yml dosyasını korumasız bırakmak. Dosya hem yönetici hem veritabanı parolasını düz metin içerir. İzni 600 yapın ve bu dosyayı sürüm kontrolüne kesinlikle koymayın.

Robot hesabı yerine kişisel hesap kullanmak. CI hattına kendi hesabınızı tanıtırsanız, siz ekipten ayrıldığınızda hat durur ve o hesabın tüm yetkileri otomasyona açılmış olur. Robot hesapları dar kapsamlı ve süreli olduğu için doğru araçtır.

Saklama kuralı yazıp çöp toplamayı unutmak. Etiketler listede kaybolur ama disk aynı kalır. İkisini birlikte zamanlayın.

Tarama eşiğini çok agresif seçmek. "Orta ve üzeri zafiyette engelle" kuralı pratikte her dağıtımı durdurur ve sonuç, politikanın tamamen kapatılması olur. Kritik seviyeden başlayıp kademeli sıkılaştırın.

Kaynakları yetersiz hesaplamak. 2 GB RAM'li bir makinede Harbor açılır ama Trivy taraması sırasında bellek yetersizliğinden servisler çöker. Tarama açacaksanız 8 GB tarafına yaklaşın.

Sıkça Sorulan Sorular#

Harbor ücretsiz mi#

Evet, Harbor Apache 2.0 lisanslı açık kaynaklı bir projedir ve CNCF çatısı altında geliştirilir; lisans ücreti yoktur. Maliyetiniz yalnızca üzerinde çalışacağı sunucu kaynaklarıdır. Kurumsal destek isteyen şirketler için ticari destek sunan sağlayıcılar bulunur ama ürünün kendisini kullanmak için hiçbir ödeme gerekmez.

Harbor için ne kadar kaynak gerekir#

Asgari yapılandırma iki çekirdek, 4 GB RAM ve 40 GB disktir; ancak zafiyet taraması açıkken bu değerler sınırda kalır. Rahat bir üretim kurulumu için dört çekirdek, 8 GB RAM ve imaj hacminize göre planlanmış 160 GB civarı disk öneririm. Disk tarafında imaj deposu, PostgreSQL verisi ve Trivy veritabanının aynı birimi paylaştığını hesaba katın.

registry:2 kurulumumdan Harbor'a nasıl geçerim#

Doğrudan bir dönüştürme aracı yoktur; en pratik yol Harbor'ı ayrı bir adreste kurup imajları yeniden göndermektir. Eski registry'den etiket listesini API ile çekip her imajı docker pull, docker tag, docker push sırasıyla aktaran kısa bir betik yeterlidir. Alternatif olarak Harbor'ın çekme tabanlı çoğaltma kuralını eski registry'ye yönlendirerek toplu aktarım yapabilirsiniz; bu yöntem daha az elle iş gerektirir.

Zafiyet taraması dağıtımı yavaşlatır mı#

Tarama, imaj gönderildikten sonra arka planda çalışır ve gönderme işlemini bekletmez; dolayısıyla docker push süresine doğrudan etkisi olmaz. Ancak "zafiyetli imajın çekilmesini engelle" politikasını açtıysanız, taraması tamamlanmamış bir imajı çekmeye çalışan dağıtım bekleyebilir. Orta boy bir imajın taraması genellikle bir dakikanın altındadır; ilk tarama, zafiyet veritabanı indirileceği için daha uzun sürer.

Harbor'ı Docker Hub aynası olarak kullanabilir miyim#

Evet, Harbor'da bir projeyi "proxy cache" olarak tanımlayıp Docker Hub'a bağlayabilirsiniz; o proje üzerinden istenen imajlar Hub'dan çekilip yerelde saklanır ve sonraki isteklerde dışarı çıkılmaz. Bu, çekme limitleri sorununu ortadan kaldırır ve dağıtım hızını artırır. İmaj yolunu harbor.firmaniz.com/proxy-proje/library/nginx:1.27 biçiminde yazmanız gerekir.

Harbor kullanıcılarını LDAP ile yönetebilir miyim#

Evet, Harbor yerel veritabanının yanı sıra LDAP, Active Directory ve OIDC ile kimlik doğrulamayı destekler. Kurulumdan sonra yönetim arayüzündeki kimlik doğrulama bölümünden modu seçersiniz; dikkat edilmesi gereken nokta, modun kurulum sonrası ilk kullanıcı oluşturulduktan sonra değiştirilmesinin kısıtlı olmasıdır. Kurumsal bir kurulum planlıyorsanız kimlik sağlayıcı kararını en baştan verin.

Harbor çöktüğünde imajlarım kaybolur mu#

Hayır, imajlar data_volume altındaki dizinde durur ve Harbor servisleri yeniden başladığında oldukları yerden çalışmaya devam eder. Asıl risk diskin kendisini ya da PostgreSQL verisini kaybetmektir; veritabanı olmadan imajlar diskte durur ama proje, yetki ve etiket bilgisi kaybolur. Bu yüzden yedeklemenin veri hacmini, veritabanını ve yapılandırma dosyasını birlikte kapsaması gerekir.

Kapanış#

Harbor, konteyner registry'sini bir dosya deposu olmaktan çıkarıp yönetilen bir platforma dönüştürür. Aklınızda kalması gereken dört alışkanlık şunlar: otomasyona daima dar kapsamlı ve süreli robot hesapları verin, tarama politikasını kritik seviyeden başlatıp kademeli sıkılaştırın, saklama kuralını ve çöp toplamayı birlikte zamanlayın, yedeklemede imaj hacmi ile veritabanını asla ayırmayın. Bu dördü yerindeyse Harbor bakımı düşük, getirisi yüksek bir bileşen olarak çalışır.

Harbor gibi kaynak isteyen ve sürekli ayakta kalması gereken bir servis için altyapı seçimi önemlidir. Disk ve RAM'i esnek şekilde büyütebileceğiniz bulut sunucu ya da yüksek performanslı VDS paketlerimiz bu iş için uygundur; kurulum, sertifika yenileme ve yükseltme süreçlerini devretmek isterseniz sunucu yönetimi hizmetimiz bunları üstlenir. Kayıt verilerinizin düzenli kopyası için yedekleme çözümümüze ve alan adı sertifikanız için SSL sayfamıza da göz atabilirsiniz.