Harbor: die Stolpersteine im Überblick

Diese Sammlung ist für den Betrieb gedacht, nicht für die erste Installation. Sie richtet sich an alle, die Harbor bereits stehen haben oder gerade aufbauen und wissen wollen, welche Eigenschaften der Registry später als Störung sichtbar werden. Der Aufbau selbst, mit Prüfbefehl nach jedem Schritt, steht im Hauptbeitrag Die eigene Registry mit Harbor. Wer dort die drei folgenreichsten Fälle bereits gelesen hat, findet sie hier erneut, damit die Liste vollständig bleibt.

Der rote Faden durch alle siebzehn Fälle ist derselbe: Harbor ist eine Registry mit einer Reihe scharfer Werkzeuge, die einzeln aktiviert und geprüft werden müssen. Fast jeder Eintrag hier entsteht aus einer Voreinstellung, die nicht das tut, was der Name vermuten lässt.

1. Harbor läuft, aber nichts wird gescannt

Symptom: Jedes Image bleibt ohne Scan-Ergebnis. Unter Administration, Interrogation Services taucht kein Scanner auf.

Ursache: Trivy ist kein Bestandteil der Standardinstallation. Ohne --with-trivy wird der Scanner-Container nicht ausgerollt.

Prüfung:

sudo docker compose ps | grep trivy

Lösung: Von Anfang an mit sudo ./install.sh --with-trivy installieren. Wurde ohne Flag installiert, muss der Installationslauf mit gesetztem Flag wiederholt werden.

2. Neu gepushte Images bleiben ohne Befund

Symptom: Trivy läuft, aber frisch hochgeladene Images erscheinen ohne Ergebnis. Ein manueller Scan liefert dagegen sofort Funde.

Ursache: Scan-on-push ist eine Projekteinstellung und standardmäßig nicht aktiv.

Prüfung:

curl -u "admin:<pass>" -k https://harbor.lab.rz.jabi-it.de/api/v2.0/projects/produktion

Im Feld metadata muss auto_scan auf "true" stehen.

Lösung: Im jeweiligen Projekt unter Configuration die Checkbox Automatically scan images on push setzen. Das ist für jedes Projekt zu wiederholen, auch für jedes neu angelegte.

3. Die Blockade verwundbarer Images wirkt scheinbar nicht

Symptom: Trotz aktivierter Blockade landen verwundbare Images weiterhin in der Registry.

Ursache: Die Option Prevent vulnerable images from running blockiert den Pull, nicht den Push. Das Image wird gespeichert, nur die Herausgabe wird verweigert.

Prüfung: Ein bewusst verwundbares Image hochladen, dann den Pull versuchen.

docker push harbor.lab.rz.jabi-it.de/produktion/testimage:1 && docker pull harbor.lab.rz.jabi-it.de/produktion/testimage:1

Der Push gelingt, der Pull muss abgewiesen werden.

Lösung: Erwartung korrigieren. Wer den Push verhindern will, braucht eine vorgelagerte Prüfung in der Pipeline. Harbor ist an dieser Stelle die letzte Instanz vor der Auslieferung, nicht die erste vor der Ablage.

4. Der Schwellwert lässt Funde durch

Symptom: Images mit gemeldeten Schwachstellen werden trotz gesetztem Schwellwert ausgeliefert.

Ursache: Der Schwellwert wirkt ab der gewählten Stufe aufwärts. Die Stufe negligible blockiert Harbor grundsätzlich nie.

Prüfung: Den Bericht abrufen und die Verteilung gegen den gesetzten Schwellwert halten.

curl -u "admin:<pass>" -k \
  "https://harbor.lab.rz.jabi-it.de/api/v2.0/projects/produktion/repositories/testimage/artifacts/1/additions/vulnerabilities"

Lösung: Den Schwellwert bewusst wählen und wissen, dass die unterste Stufe durchgeht. Wer auch negligible erfassen will, wertet die Vulnerabilities-API zusätzlich selbst aus.

5. Das Proxy-Cache-Projekt vererbt die Reichweite des Upstream-Kontos

Symptom: Über das Proxy-Cache-Projekt lassen sich private Images der Zielregistry ziehen, die dort eigentlich geschützt sind.

Ursache: Ein Proxy-Cache-Projekt kann jedes Image der Zielregistry ziehen, auf das das im Registry-Endpoint hinterlegte Zugangskonto Zugriff hat. Damit können alle Harbor-Nutzer mit Zugriff auf das Proxy-Projekt jedes Image ziehen, das dem Upstream-Konto offensteht.

Prüfung: Mit einem gewöhnlichen Projektmitglied testen, ob sich ein privates Upstream-Image ziehen lässt, das dieses Mitglied nicht sehen dürfte. Gelingt der Pull, ist das Upstream-Konto zu breit berechtigt.

Lösung: Für die Zielregistry ein Konto mit minimalen Rechten anlegen und ausschließlich dieses im Endpoint hinterlegen. Den Zugriff auf das Proxy-Projekt eng halten. Dieser Punkt ist der Grund, warum ein Proxy-Cache-Projekt kein beiläufiger Schalter ist.

6. Gecachte Images verschwinden nach sieben Tagen

Symptom: Ein Image, das schon einmal gezogen wurde, wird später erneut vom Upstream geholt. Im abgeschotteten Netz schlägt der Pull dann fehl.

Ursache: Harbor legt für jedes neue Proxy-Cache-Projekt automatisch eine Aufbewahrungsregel von sieben Tagen an. Ältere gecachte Artefakte werden entfernt.

Prüfung: Im Proxy-Projekt unter Policy, Tag Retention die automatisch angelegte Regel ansehen.

Lösung: Die Regel bewusst prüfen und bei Bedarf anpassen, statt das Proxy-Projekt als unbegrenzten Cache zu behandeln.

7. Der Push ins Proxy-Projekt bricht die Pipeline ab

Symptom: Der Push in das Proxy-Cache-Projekt wird abgewiesen, die CI-Pipeline bricht ab.

Ursache: In ein Proxy-Cache-Projekt kann grundsätzlich nicht gepusht werden.

Prüfung: docker push harbor.lab.rz.jabi-it.de/dockerhub-proxy/test:1 muss fehlschlagen, ein Push in ein reguläres Projekt muss gelingen.

Lösung: Eigene Images in ein normales Projekt legen und das Proxy-Cache-Projekt strikt als Lesespiegel behandeln.

8. Das Robot-Secret ist weg

Symptom: Das Secret eines Robot-Accounts wurde nicht gesichert und ist nirgends mehr auffindbar.

Ursache: Harbor speichert Robot-Secrets nicht. Nach dem Anlegen gibt es keinen Weg, das Secret wieder auszulesen.

Prüfung:

echo -n "<secret>" | docker login harbor.lab.rz.jabi-it.de -u 'robot$ci' --password-stdin

Die Ausgabe muss Login Succeeded lauten. Die einfachen Anführungszeichen sind nicht optional, sonst frisst die Shell das Dollarzeichen.

Lösung: Das Secret unmittelbar beim Anlegen sichern. Ist es verloren, hilft nur ein neuer Robot-Account.

9. Der Login mit dem Robot-Namen schlägt fehl

Symptom: docker login weist den Robot-Account ab, obwohl das Secret korrekt ist.

Ursache: Beim Login zählt nur der vollständige Name aus Präfix und Kontoname, nicht der in der Oberfläche eingetragene Name allein. Der Standardpräfix lautet robot$. Aus einem System-Robot namens ci wird damit robot$ci. Der Präfix ist änderbar und wirkt dann auf alle bestehenden und künftigen System- und Projekt-Robots, ausgenommen Konten aus Harbor v2.1 und älter, die weiterhin robot$ verwenden.

Prüfung:

curl -u "admin:<pass>" -k https://harbor.lab.rz.jabi-it.de/api/v2.0/robots

Das Feld name zeigt den Namen, unter dem der Login erfolgen muss.

Lösung: Den vollständigen Namen aus der API oder der Oberfläche übernehmen. Wurde der Präfix systemweit geändert, gilt der neue Präfix nicht für Konten, die unter Harbor v2.1 oder älter entstanden sind. Diese behalten robot$.

10. Nach etwa einem Monat schlagen alle Pulls fehl

Symptom: Im Cluster erscheinen ImagePullBackOff, Pipeline-Logins scheitern, ohne dass etwas geändert wurde.

Ursache: Robot-Accounts laufen standardmäßig nach 30 Tagen ab.

Prüfung:

curl -u "admin:<pass>" -k https://harbor.lab.rz.jabi-it.de/api/v2.0/robots

Das Feld expires_at der betroffenen Konten prüfen.

Lösung: Die Ablaufzeit bewusst setzen. Entweder Never Expired für Systemkonten oder den globalen Wert Robot Token Expiration (Days) anpassen und die Rotation einplanen.

11. Der Trivy-Adapter liefert im abgeschotteten Netz leere Befunde

Symptom: Der Adapter meldet Fehler oder gibt Ergebnisse ohne Funde zurück.

Ursache: Mit skip_update auf true lädt der Adapter keine Datenbank mehr. Sie muss dann selbst bereitgestellt und an einem fest vorgegebenen Pfad eingehängt werden.

Prüfung:

sudo docker exec -it trivy-adapter ls -l /home/scanner/.cache/trivy/db/trivy.db

Dort muss eine Datei mit plausiblem Datum liegen.

Lösung: Entweder skip_update auf false lassen und dem Adapter den Weg nach draußen öffnen, oder die Datenbank manuell bereitstellen und exakt unter /home/scanner/.cache/trivy/db/trivy.db einhängen. Alternativ db_repository in der harbor.yml auf eine interne OCI-Quelle setzen. Der Adapter kennt dafür auch die Umgebungsvariablen SCANNER_TRIVY_SKIP_UPDATE und SCANNER_TRIVY_DB_REPOSITORY.

12. GitHub bremst den Datenbank-Download aus

Symptom: Die Trivy-Datenbank lässt sich nicht aktualisieren, in den Logs stehen Rate-Limit-Meldungen von GitHub.

Ursache: Ohne Token gilt das niedrige anonyme Rate-Limit für den Download.

Prüfung:

sudo docker logs trivy-adapter 2>&1 | grep -i "rate limit"

Lösung: In der harbor.yml unter trivy einen github_token setzen. Laut Konfigurationsreferenz steigt das Limit damit auf 5000 Anfragen pro Stunde.

13. Der Docker-Client verweigert die Verbindung

Symptom: docker login oder docker push scheitert mit server gave HTTP response to HTTPS client.

Ursache: Harbor liefert keine Zertifikate mit. Läuft die Instanz über HTTP, lehnt der Docker-Client sie ohne ausdrückliche Ausnahme ab.

Prüfung: docker login harbor.lab.rz.jabi-it.de muss Login Succeeded liefern statt eines TLS-Fehlers.

Lösung: Harbor auf HTTPS umstellen und eigene Zertifikate bereitstellen. Wer bewusst HTTP fährt, muss auf jedem Client die Option --insecure-registry beziehungsweise den entsprechenden Eintrag in /etc/docker/daemon.json setzen und Docker neu starten.

14. Die Zertifikatskette bricht ab

Symptom: Der Zugriff scheitert an einer unvollständigen Kette, obwohl das Serverzertifikat gültig ist.

Ursache: Harbor erwartet Serverzertifikat und Zwischenzertifikate in einer Datei.

Prüfung:

openssl s_client -connect harbor.lab.rz.jabi-it.de:443 -showcerts </dev/null

Die Ausgabe muss die vollständige Kette zeigen und mit Verify return code: 0 (ok) enden.

Lösung: Das Zwischenzertifikat anhängen und dem Ergebnis auf Betriebssystemebene vertrauen.

cat intermediate-certificate.pem >> harbor.lab.rz.jabi-it.de.crt

Unter Ubuntu folgt anschließend update-ca-certificates, unter Red Hat update-ca-trust.

15. Hinter dem Reverse-Proxy zeigen Redirects auf das falsche Schema

Symptom: Hinter einem vorgelagerten nginx oder Loadbalancer verhält sich Harbor fehlerhaft, Weiterleitungen zeigen auf http:// statt https://.

Ursache: Der vorgelagerte eigene Proxy setzt den Header X-Forwarded-Proto bereits, und der von Harbor mitgelieferte nginx setzt ihn zusätzlich. Die Troubleshooting-Doku behandelt genau diesen Konflikt.

Prüfung: Die von Harbor erzeugte nginx-Konfiguration auf die betreffende Zeile durchsuchen.

grep -n 'X-Forwarded-Proto' common/config/nginx/nginx.conf

Lösung: Wenn der eigene vorgelagerte Proxy den Header bereits setzt, die Zeile proxy_set_header X-Forwarded-Proto $scheme; in common/config/nginx/nginx.conf in den Blöcken location /, location /v2/ und location /service/ entfernen und Harbor anschließend neu ausrollen.

16. Die Konfiguration lässt sich nicht mehr ändern

Symptom: Änderungen in der Oberfläche werden nicht übernommen oder die Felder sind ausgegraut.

Ursache: Die Umgebungsvariable CONFIG_OVERWRITE_JSON ist gesetzt. Ist sie das, lässt sich die Konfiguration weder in der Oberfläche noch auf der Kommandozeile ändern. Aktualisieren oder Entfernen geht nur über die Variable selbst und einen Neustart des Containers.

Prüfung:

curl -u "admin:<pass>" -H "Content-Type: application/json" -ki https://harbor.lab.rz.jabi-it.de/api/v2.0/configurations

Lösung: CONFIG_OVERWRITE_JSON nur einsetzen, wenn die Konfiguration bewusst deklarativ und ausschließlich über diese Variable geführt werden soll. Wer sie ohne diesen Vorsatz setzt, sperrt sich selbst aus. Ändern lässt sich die Konfiguration ansonsten per API über GET und PUT auf /api/v2.0/configurations mit Basic Auth.

17. Das Upgrade migriert die Konfiguration nicht

Symptom: Nach dem Upgrade startet Harbor nicht sauber oder arbeitet mit einer Konfiguration, die nicht zur neuen Version passt.

Ursache: Zwei Vorgaben der Upgrade-Doku werden übersehen. Erstens deckt die aktuelle Anleitung ausschließlich Migrationen ab v2.12.0 ab, ältere Stände müssen über den Migrationsleitfaden der jeweiligen Zwischenversion gehen. Zweitens migriert das prepare-Image die harbor.yml nur mit dem Unterkommando migrate und dem Parameter -i. Ohne beides bleibt die Konfigurationsdatei unverändert.

Prüfung:

curl -k https://harbor.lab.rz.jabi-it.de/api/v2.0/systeminfo

Das Feld harbor_version zeigt den laufenden Stand. Liegt er unter v2.12.0, ist die aktuelle Anleitung nicht anwendbar.

Lösung: Der dokumentierte Ablauf lautet: Container stoppen, danach Verzeichnis und Datenbank sichern, dann migrieren und neu installieren. Die Dokumentation schreibt das Backup vor jeder Datenmigration in Großbuchstaben vor.

cd harbor
docker compose down
mv harbor /my_backup_dir/harbor
cp -r /data/database /my_backup_dir/
docker pull goharbor/prepare:[tag]
docker run -it --rm -v /:/hostfs goharbor/prepare:[tag] migrate -i ${path to harbor.yml}
./install.sh

Die Schema- und Datenmigration der Datenbank erledigt der Core beim Start, die stoßen Sie nicht selbst an. Nutzen Sie eine externe Datenbank, gilt seit Harbor v2.9 eine Mindestversion von PostgreSQL 12. Nach dem Upgrade muss sudo docker compose ps wieder alle Container mit Up zeigen.

Wie Sie diese Liste einsetzen

Ich empfehle, diese Sammlung einmal vollständig durchzugehen, bevor die erste Pipeline an Harbor hängt, und danach als Nachschlagewerk zu behandeln. Die Fälle 1 bis 5 entscheiden darüber, ob die Sicherheitsfunktion überhaupt wirkt. Die Fälle 8 bis 10 entscheiden darüber, ob der Betrieb nach dem ersten Monat noch läuft. Die Fälle 11 bis 17 sind Umgebungsfragen, die auftreten, sobald Harbor hinter einem Proxy, in einem abgeschotteten Netz, unter deklarativer Konfiguration oder im Upgrade betrieben wird.

Der zugehörige Aufbau mit Voraussetzungen, harbor.yml, Installation mit Scanner, Proxy-Cache und Robot-Accounts steht im Hauptbeitrag Die eigene Registry mit Harbor: scannen, cachen, absichern. Dort finden Sie auch die Vergleichstabelle der drei Installationswege.

Sie wollen kontrollieren, welche Images in Ihre Systeme gelangen, und sie vorab prüfen? Ich baue Registry- und Scanning-Setups, die Sicherheit an die Quelle holen, passend zur Größe Ihrer Umgebung. Mehr unter Infrastruktur & Cloud, das Erstgespräch ist unverbindlich.