DevOps 8 Min Lesezeit

Harbor Container Registry selbst hosten 2026

Q: Wie migriere ich von Docker Hub zu Harbor?

Am einfachsten mit skopeo copy: skopeo copy docker://docker.io/library/nginx:1.27 docker://registry.firma.de/platform/nginx:1.27. Für Massenmigrationen schreibst du eine Schleife über eine Image-Liste oder nutzt die Harbor-Replikationsfunktion mit einem Docker-Hub-Endpoint als Pull-Quelle. Plane für 500 Images etwa 2–4 Stunden ein.

Warum Harbor 2026 die Docker Registry ablöst

Die offizielle registry:2 von Docker ist seit Jahren funktional eingefroren. Sie kann Images pushen und pullen – und das war es dann auch. Kein Web-UI, keine Benutzerverwaltung, kein Vulnerability-Scanning, keine Replikation zwischen Standorten. Wer 2026 mehr als zehn Images verwaltet oder mehr als drei Entwickler im Team hat, stößt an Grenzen, die sich mit Harbor sauber lösen lassen.

Harbor ist ein CNCF-Graduated-Projekt und hat mit Version 2.13 (Release Ende 2025) einen Reifegrad erreicht, bei dem die Installation in unter 30 Minuten erledigt ist. Die Registry bringt von Haus aus mit: rollenbasierte Zugriffskontrolle (RBAC), Projekt-Isolation, Trivy-basiertes Scanning auf CVEs, Webhooks, Quota-Verwaltung pro Projekt, Image-Retention-Policies, Proxy-Cache für Docker Hub, Replikation zu entfernten Registries und OIDC-Anbindung an Keycloak oder Azure AD.

Der entscheidende Punkt 2026: Die EU-Regulatorik rund um den Cyber Resilience Act verlangt für ausgelieferte Software SBOMs und nachvollziehbare Herkunftsnachweise. Harbor liefert Cosign-Signaturprüfung, Notary-v2-Support und Access-Logs, die Prüfer akzeptieren. Eine nackte registry:2 liefert davon nichts.

Dieser Guide zeigt die komplette Strecke: Hardware-Dimensionierung, Installation per Docker Compose und Helm, TLS mit Let's Encrypt, Projektstruktur, Trivy-Scanning, Replikation, Backup-Strategie und Kosten. Alle Befehle sind auf Harbor 2.13 getestet.

Hardware-Dimensionierung und Voraussetzungen

Harbor ist kein Leichtgewicht. Die Installation besteht aus neun Containern: Core, Portal, Jobservice, Registry, Database (PostgreSQL 15), Redis, Trivy, Proxy (Nginx) und optional Exporter. Für ein Team bis 50 Entwickler mit 2.000 Images reicht folgende Konfiguration:

Teamgröße	vCPU	RAM	Storage	Empfehlung
bis 10 Devs	2	4 GB	100 GB SSD	Hetzner CX22 (4,35 €/Monat)
bis 50 Devs	4	8 GB	500 GB NVMe	Hetzner CPX31 (15,59 €/Monat)
bis 200 Devs	8	16 GB	2 TB NVMe	Hetzner CCX33 (63,84 €/Monat)
Enterprise	16+	32 GB+	S3/MinIO	K8s-Cluster + Object Storage

Der Storage-Bedarf wächst schneller als erwartet. Ein Ubuntu-22.04-Base-Image belegt 78 MB, ein Node.js-Image mit node_modules schnell 1,2 GB. Bei 50 Images pro Woche und 30 Tagen Retention landest du bei 200–400 GB. Harbor dedupliziert Layer innerhalb eines Projekts nicht automatisch – die Registry speichert Blobs content-addressed, doppelte Layer werden also sehr wohl geteilt. Das ist ein wichtiger Vorteil gegenüber einfachen Tar-Archiven.

Als Betriebssystem empfehle ich Ubuntu 24.04 LTS oder Debian 12. Beide haben Kernel 6.x, was für OverlayFS-Performance bei vielen kleinen Layer-Reads relevant ist. Docker Engine ab 27.0 oder Podman 5.x sind Pflicht. Für den externen Zugriff brauchst du einen DNS-Eintrag (z. B. registry.firma.de) und offene Ports 443 und optional 80 für ACME-Challenges.

Installation per Docker Compose

Der schnellste Weg führt über das offizielle Online-Installer-Tarball. Lade die aktuelle Version und entpacke sie:

wget https://github.com/goharbor/harbor/releases/download/v2.13.0/harbor-online-installer-v2.13.0.tgz
tar xzvf harbor-online-installer-v2.13.0.tgz
cd harbor
cp harbor.yml.tmpl harbor.yml

In der harbor.yml setzt du Hostname, TLS-Pfade und das Admin-Passwort. Ein Minimalbeispiel:

hostname: registry.firma.de
http:
  port: 80
https:
  port: 443
  certificate: /etc/letsencrypt/live/registry.firma.de/fullchain.pem
  private_key: /etc/letsencrypt/live/registry.firma.de/privkey.pem
harbor_admin_password: "EinSehrLangesPasswort2026!"
database:
  password: "dbpasswort-bitte-aendern"
  max_idle_conns: 100
data_volume: /data/harbor
trivy:
  ignore_unfixed: false
  skip_update: false
  severity: HIGH,CRITICAL

Danach startest du die Installation mit aktiviertem Trivy-Scanner:

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

Der Installer zieht rund 1,8 GB Images, initialisiert PostgreSQL und startet alle Container. Nach etwa 3–5 Minuten ist das Web-UI unter https://registry.firma.de erreichbar. Login: admin plus das Passwort aus der YAML. Ändere es sofort über das UI unter Administration → Users.

Prüfe anschließend den Zustand aller Container mit docker compose ps. Erwartet werden neun Services im Status running oder healthy. Der harbor-jobservice zeigt gelegentlich restarting – das liegt meist an falschen Volume-Permissions auf /data/harbor. Ein chown -R 10000:10000 /data/harbor löst das Problem.

Installation im Kubernetes-Cluster mit Helm

Für Produktivumgebungen ist Helm der sauberere Weg. Das offizielle Chart liegt unter goharbor/harbor und wird über Artifact Hub verteilt:

helm repo add harbor https://helm.goharbor.io
helm repo update
helm install harbor harbor/harbor \
  --namespace harbor --create-namespace \
  --set expose.type=ingress \
  --set expose.ingress.hosts.core=registry.firma.de \
  --set expose.tls.enabled=true \
  --set externalURL=https://registry.firma.de \
  --set persistence.persistentVolumeClaim.registry.size=500Gi \
  --set trivy.enabled=true \
  --set trivy.severity=HIGH,CRITICAL \
  --set database.type=external \
  --set database.external.host=postgres.intern \
  --set redis.type=external

Für größere Setups lohnt sich der externe PostgreSQL und Redis. Der in-cluster betriebene PostgreSQL 15 ist für Testumgebungen okay, aber bei mehr als 100 gleichzeitigen API-Calls wird er zum Flaschenhals. Ein managed PostgreSQL (z. B. Hetzner, Scaleway oder AWS RDS) mit 4 vCPU und 8 GB RAM kostet rund 40–90 €/Monat und entlastet den Cluster spürbar.

Als Object Storage empfehle ich S3 oder MinIO statt PVC. Das Chart unterstützt das über persistence.imageChartStorage.type=s3. Vorteil: unbegrenztes Wachstum, kein PVC-Resize-Drama, und die Registry-Container werden stateless. MinIO auf eigener Hardware kostet dich nur den Storage – 4 TB NVMe bei Hetzner liegen bei rund 200 €/Monat als dediziertes Blech.

TLS, Reverse Proxy und Netzwerksicherheit

Harbor ohne TLS ist 2026 keine Option mehr – Docker und containerd verweigern bei insecure-registries ohnehin den Dienst in den meisten CI-Setups. Nutze Let's Encrypt mit certbot im Standalone-Modus vor der Harbor-Installation, oder Terminiere TLS an einem vorgelagerten Nginx/Traefik.

Bei Traefik als Ingress-Controller reicht ein IngressRoute mit certResolver: letsencrypt. Wichtig: Setze externalURL in der Harbor-Konfiguration auf die öffentliche HTTPS-URL, sonst generiert das UI falsche Pull-Befehle und Webhook-URLs.

Für die Netzwerksicherheit gilt: Exponiere niemals Port 8080 (Harbor Core) direkt. Der interne Nginx-Proxy sollte der einzige Container mit veröffentlichtem Port sein. In Kubernetes nutzt du NetworkPolicies, die eingehenden Traffic nur vom Ingress-Namespace erlauben.

Ein häufiger Fehler: fehlender X-Forwarded-Proto-Header. Ohne ihn erkennt Harbor HTTPS-Anfragen nicht und leitet in Redirect-Schleifen. Setze im Proxy:

proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
client_max_body_size 0;

client_max_body_size 0 ist essenziell – sonst brechen Image-Pushes bei 1 MB ab. Das ist der häufigste Support-Fall bei Harbor-Neulingen.

Projekte, Nutzer und RBAC richtig strukturieren

Harbor organisiert Images in Projekten. Jedes Projekt hat eigene Mitglieder, Quotas, Scan-Policies und Retention-Regeln. Eine bewährte Struktur für ein 50-Personen-Unternehmen:

platform/ – Basis-Images (Ubuntu, Alpine, Distroless), nur Platform-Team darf pushen
backend/ – Services der Backend-Teams, Push für CI-Service-Accounts
frontend/ – Web-Apps und Static-Builds
proxy-cache/ – Proxy-Cache-Projekte für Docker Hub, Quay, GHCR
sandbox/ – Experimente, Quota 20 GB, Retention 7 Tage

Rollen in Harbor: Limited Guest (nur Pull), Developer (Pull + Push), Maintainer (zusätzlich Scan, Retention, Labels), Project Admin (Mitglieder verwalten). Für CI/CD nutzt du Robot Accounts statt menschlicher Nutzer. Ein Robot Account pro Repository mit Pull-only-Rechten ist Best Practice.

Für die Authentifizierung bindest du OIDC an. Keycloak, Azure AD, Okta und Google Workspace werden nativ unterstützt. In der harbor.yml:

oidc:
  name: keycloak
  endpoint: https://sso.firma.de/realms/main
  client_id: harbor
  client_secret: "geheim"
  scope: openid,profile,email,groups
  groups_claim: groups
  admin_group: harbor-admins
  verify_cert: true
  auto_onboard: true

Mit auto_onboard: true werden Nutzer beim ersten Login automatisch angelegt. Die Gruppenzuordnung über admin_group spart manuelle Rechtevergabe. Achtung: OIDC-Nutzer können sich nicht mit lokalem Passwort einloggen – halte immer einen lokalen Admin-Account als Notfallzugang bereit.

Trivy-Scanning und Vulnerability-Policies

Harbor integriert Trivy als Scanner. Standardmäßig scannt es beim Push und danach täglich um 02:00 Uhr. Die Konfiguration in harbor.yml steuert Schweregrade:

trivy:
  ignore_unfixed: false
  skip_update: false
  skip_java_db_update: false
  offline_scan: false
  insecure: false
  severity: HIGH,CRITICAL
  timeout: 10m0s

Für jedes Projekt aktivierst du unter Configuration → Deployment security die Option Prevent vulnerable images from running. Damit blockiert Harbor den Pull, wenn ein Image CVEs über dem Schwellwert enthält. Der Schwellwert lässt sich pro Projekt auf Critical, High oder Medium setzen. Meine Empfehlung: Produktionsprojekte auf Critical, Staging auf High.

Wichtig zu wissen: Trivy scannt nur OS-Packages und Sprachabhängigkeiten (npm, pip, Go modules, Maven). Statisch gelinkte Binaries ohne SBOM bleiben unsichtbar. Ergänze deshalb Cosign-Signaturprüfung, wenn du Images von Drittanbietern beziehst.

Für die automatische Prüfung im CI nutzt du die Harbor-API:

curl -u "robot\$ci:PASSWORT" \
  "https://registry.firma.de/api/v2.0/projects/backend/repositories/myapp/artifacts/latest?with_scan_overview=true" \
  | jq '.scan_overview."application/vnd.security.vulnerability.report; version=1.1".summary'

Die Antwort enthält Zähler für Critical, High, Medium und Low. Ein CI-Job bricht den Build ab, wenn Critical > 0. Das ist die pragmatischste Gate-Lösung ohne zusätzliche Tools.

Replikation und Proxy-Cache für Docker Hub

Zwei Funktionen sparen massiv Bandbreite: Proxy-Cache und Replikation. Der Proxy-Cache ist ein Pull-Through-Cache für entfernte Registries. Statt bei jedem Build docker.io/library/node:22 von Docker Hub zu ziehen, holt Harbor das Image einmal und liefert es danach lokal aus.

docker pull registry.firma.de/proxy-cache/library/node:22

Das reduziert die Build-Zeit in CI um 40–70 %, weil Docker Hub rate-limits (100 Pulls/6h für anonyme Nutzer) komplett umgangen werden. Konfiguriere den Proxy-Cache pro Projekt unter Registries → New Endpoint und weise ihn dann als Projekt-Proxy zu.

Die Replikation kopiert Images zwischen Harbor-Instanzen oder zu Cloud-Registries (AWS ECR, GCR, ACR, Quay). Typische Szenarien: Edge-Standorte mit lokaler Registry, die von einem zentralen Harbor replizieren, oder Push-Spiegelung zu ECR für Lambda-Deployments.

Modus	Richtung	Anwendungsfall
Push-based	lokal → remote	Spiegelung zu ECR/GCR
Pull-based	remote → lokal	Edge-Cache, Multi-Region
Proxy-Cache	on-demand	Docker Hub Offloading

Replikationsregeln lassen sich per Label filtern (release=prod) und zeitlich planen (Cron). Bei Pull-basierten Regeln läuft die Replikation alle 5 Minuten bis 24 Stunden – je nach Konfiguration. Für Multi-Region-Setups mit 500 GB Images rechne mit 2–6 Stunden initialer Übertragung bei 100 Mbit/s.

Backup, Upgrade und Wartung

Harbor hat drei Backup-relevante Komponenten: PostgreSQL-Datenbank, Registry-Blobs und die Konfigurationsdateien. Ein vollständiges Backup-Skript:

#!/bin/bash
set -e
DATE=$(date +%Y%m%d-%H%M)
BACKUP=/backup/harbor-$DATE
mkdir -p $BACKUP

# Datenbank
docker exec harbor-db pg_dumpall -U postgres | gzip > $BACKUP/db.sql.gz

# Konfiguration
tar czf $BACKUP/config.tar.gz /opt/harbor/harbor.yml /opt/harbor/common/config

# Registry-Blobs (rsync, inkrementell)
rsync -a --delete /data/harbor/registry/ /backup/registry-mirror/

# Nur DB + Config in Rotation behalten
find /backup -name "harbor-*" -mtime +30 -exec rm -rf {} \;

Die Registry-Blobs müssen nicht täglich vollständig gesichert werden – sie sind immutable. Ein wöchentlicher rsync reicht. Kritisch ist die Datenbank: Sie enthält Projekte, Nutzer, Webhooks, Scan-Reports und Replikationsregeln. Ohne sie sind die Blobs nutzlos, weil die Metadaten fehlen.

Für Upgrades gilt: Immer die Release-Notes lesen, denn zwischen Minor-Versionen ändert sich gelegentlich das Datenbankschema. Der Ablauf ist:

Backup erstellen (siehe oben)
docker compose down im Harbor-Verzeichnis
Neues Installer-Tarball entpacken, harbor.yml übernehmen
./install.sh --with-trivy ausführen
Logs prüfen: docker compose logs -f core

Ein Upgrade von 2.12 auf 2.13 dauert typischerweise 8–15 Minuten inklusive Datenbankmigration. Plane ein Wartungsfenster von 30 Minuten ein. Downgrades werden nicht unterstützt – deshalb ist das Backup vor jedem Upgrade Pflicht.

CI/CD-Integration in GitLab, GitHub und Jenkins

Die Anbindung an GitLab CI ist in drei Zeilen erledigt:

build:
  stage: build
  script:
    - echo "$CI_REGISTRY_PASSWORD" | docker login registry.firma.de -u "$CI_REGISTRY_USER" --password-stdin
    - docker build -t registry.firma.de/backend/myapp:$CI_COMMIT_SHA .
    - docker push registry.firma.de/backend/myapp:$CI_COMMIT_SHA

Für GitHub Actions nutzt du docker/login-action@v3 mit Robot-Account-Credentials aus den Repository-Secrets. Wichtig: Robot-Account-Namen enthalten einen Backslash (robot$ci-backend), der in YAML escaped werden muss – in GitHub Actions als robot\$ci-backend.

In Jenkins empfehle ich das Credentials-Binding-Plugin und einen Shared-Library-Step, der Login, Build, Push und Scan-Gate kapselt. Der Scan-Gate-Job wartet nach dem Push 30–60 Sekunden, bis Trivy fertig ist, und fragt dann die API ab. Bei großen Images (über 1 GB) dauert der Scan auch mal 3 Minuten – plane das im Pipeline-Timeout ein.

Ein Praxis-Tipp: Tagge Images immer mit dem Git-Commit-SHA und einem beweglichen Tag wie main oder staging. Die Retention-Policy sollte nur SHA-Tags behalten und bewegliche Tags nach 14 Tagen löschen. So bleibt die Registry schlank.

Kosten, Alternativen und Fazit

Selfhosting ist 2026 günstiger als die meisten denken. Ein Vergleich für ein Team mit 50 Entwicklern und 500 GB Storage:

Lösung	Monatliche Kosten	Scanning	RBAC	Replikation
Harbor self-hosted (Hetzner CPX31)	~16 €	Trivy inkl.	vollständig	ja
Docker Hub Team	~90 € (9 $/User)	begrenzt	basic	nein
GitHub Container Registry	~40 € Storage	CodeQL	über GitHub	nein
AWS ECR	~55 € (0,10 $/GB)	Inspector extra	IAM	Cross-Region
Harbor Cloud (Managed)	ab 200 €	Trivy inkl.	vollständig	ja

Der reine Serverpreis ist aber nicht alles. Rechne mit 4–8 Stunden initialem Setup und 2–4 Stunden Wartung pro Monat für Upgrades, Backup-Monitoring und Nutzerverwaltung. Bei einem internen Stundensatz von 80 € sind das 160–320 €/Monat an Personalkosten. Wer das scheut, fährt mit einem Managed-Harbor oder ECR besser.

Alternativen mit anderen Schwerpunkten: Zot ist eine schlanke OCI-native Registry in Go, die mit 200 MB RAM auskommt und keine Datenbank braucht – ideal für Edge-Deployments. Distribution (registry:3) hat 2025 endlich ein Web-UI und OCI-1.1-Support bekommen, bleibt aber funktional deutlich hinter Harbor. Quay ist seit der Red-Hat-Übernahme stark auf OpenShift fokussiert.

Mein Fazit: Harbor ist 2026 die beste Wahl für Teams ab fünf Entwicklern, die Wert auf Scanning, RBAC und EU-Datenhoheit legen. Der Betriebsaufwand ist überschaubar, die Community aktiv und die Dokumentation exzellent. Wer nur drei Images pro Woche baut, sollte bei GHCR bleiben – für alles darüber lohnt sich der eigene Harbor.

FAQ

Wie viel RAM braucht Harbor mindestens?

Für eine Testinstanz reichen 4 GB RAM, produktiv solltest du 8 GB einplanen. Trivy allein belegt bei einem Scan 1–2 GB, PostgreSQL rund 500 MB und die Registry-Core-Container zusammen etwa 1 GB. Bei weniger als 4 GB kommt es regelmäßig zu OOM-Kills des Jobservice.

Kann ich Harbor ohne eigene Domain betreiben?

Technisch ja, praktisch nein. Docker und containerd verlangen für unsichere Registries einen Eintrag in daemon.json unter insecure-registries. Das musst du auf jedem Client und in jedem Kubernetes-Node pflegen – bei mehr als fünf Nodes wird das zum Albtraum. Nutze stattdessen eine Subdomain mit Let's Encrypt, das kostet nichts und spart Stunden.

Wie migriere ich von Docker Hub zu Harbor?

Am einfachsten mit skopeo copy: skopeo copy docker://docker.io/library/nginx:1.27 docker://registry.firma.de/platform/nginx:1.27. Für Massenmigrationen schreibst du eine Schleife über eine Image-Liste oder nutzt die Harbor-Replikationsfunktion mit einem Docker-Hub-Endpoint als Pull-Quelle. Plane für 500 Images etwa 2–4 Stunden ein.

Was kostet Harbor im Vergleich zu AWS ECR wirklich?

ECR kostet 0,10 $/GB/Monat Storage plus 0,09 $/GB Datenübertragung. Bei 500 GB und 2 TB Traffic landest du bei rund 230 $/Monat. Ein Hetzner-Server mit 2 TB NVMe und 20 TB Traffic kostet 63 €/Monat – also etwa ein Drittel. Dafür fehlen dir bei Selfhosting Managed-Backups und SLA.

Unterstützt Harbor OCI Artifacts wie Helm Charts und WASM?

Ja, seit Version 2.0 vollständig. Harbor kann Helm Charts, Cosign-Signaturen, SBOMs und WebAssembly-Module als OCI Artifacts speichern. Die Signaturen werden im UI mit einem Häkchen angezeigt, wenn du Notary oder Cosign aktiviert hast. Für Helm nutzt du helm push mychart-0.1.0.tgz oci://registry.firma.de/charts.

Wie sichere ich Harbor gegen Ransomware ab?

Drei Maßnahmen sind entscheidend: Erstens Backups auf ein immutables Ziel (S3 Object Lock oder Borg mit Append-Only-Repo). Zweitens Registry-Blobs als read-only mounten, wo möglich. Drittens Robot Accounts mit minimalen Rechten und kurzer Laufzeit. Zusätzlich hilft die Harbor-Retention-Policy, alte Tags automatisch zu löschen, was die Angriffsfläche reduziert.