Die quay.io-Falle: Container-Image-Tags über mehrere Registries validieren

Hin und wieder sagt dir ein CI-Check, den du kaum wahrnimmst, etwas Wahres, indem er auf überraschende Weise scheitert. Unser Image-Tag-Validator – das Skript, das jede Image-Referenz in unseren Compose-Dateien vor Tippfehlern und verschwundenen Tags schützt – fing an, bei einem Tool zu scheitern und hörte nicht mehr auf. Das Tool war MinIO. Der Validator beharrte darauf, dass der latest-Tag nicht existiere. MinIO ist ein hochkarätiger, stark genutzter Objektspeicher; natürlich existiert der Tag.

Der Validator lag falsch – und zwar aus einem interessanten Grund: Er fragte die falsche Registry.

Die Realität zweier Registries bei Image-Tags

Die meiste Software, die du per docker pull beziehst, kommt von Docker Hub; ein naiver Validator spricht deshalb nur einen Endpunkt an. Er holt die Tag-Liste von Docker Hub und ist fertig. Diese Annahme brach bei MinIO stillschweigend, weil das MinIO-Image eine Eigenheit hat: Seine RELEASE- und latest-Tags werden nur auf quay.io veröffentlicht, nicht auf Docker Hub.

Das ergibt einen täuschend spezifischen Fehler:

$ curl -s "https://hub.docker.com/v2/repositories/minio/minio/tags/latest" | jq .name
null

Docker Hub liefert null/„not found", sogar für einen Tag, der offensichtlich existiert. docker pull minio/minio:latest funktioniert problemlos (der Daemon löst das richtige Backend auf). Aber eine Tag-Listen-HTTP-Anfrage an Docker Hub für diesen Tag liefert einen 404. Dein Validator liest „Tag fehlt" und markiert ein völlig gutes Image – was bei einem harten Gate jede Pipeline blockiert, die es referenziert.

Tags auf beliebigen Registries korrekt lesen

Der Fix besteht darin, die Registry nicht anzunehmen, sondern herauszufinden, wo ein Tag wirklich lebt. Das allgemeine Muster funktioniert über Docker Hub und quay.io hinweg:

1. Bestimmen, welche Registry gefragt wird. Für Images, deren Pinning du selbst setzt, weißt du es bereits. Für Drittanbieter-Images pflege eine kleine Zuordnung, die bekannte Projekte auf ihre korrekte Registry routet – z. B. minio/minio und minio/mc auf quay.io.

2. Das Manifest anfordern, nicht die Tag-Liste. Ein HEAD gegen die Manifest-URL ist der robusteste Existenzcheck, weil er auch Registries übersteht, deren Tag-Listen-APIs sich unterscheiden.

3. Wo nötig anonym authentifizieren. quay.io erwartet ein Bearer-Token. Der Ablauf: eine Challenge abfragen, Credentials (hier: anonym) gegen ein Token tauschen, dann das Manifest mit Authorization: Bearer <token> per HEAD prüfen.

# quay.io anonymer Bearer-Token-Flow
token=$(curl -s "https://quay.io/v2/auth?service=quay.io&scope=repository:minio/minio:pull" \
  | jq -r .token)
curl -sI -H "Authorization: Bearer $token" \
  "https://quay.io/v2/minio/minio/manifests/latest"

Ein 200 beim HEAD bedeutet, dass der Tag existiert. Zusammen mit der kleinen Routing-Tabelle (minio/* → quay.io) verlässt sich der Validator nun auf echte Fakten statt auf die Annahmen einer einzigen Registry.

Lektionen für jeden Image-Tag-Validator

• Die Tag-Listen-API einer Registry ist kein Evangelium. Ein Docker-Hub- 404 für einen gültigen Tag ist ein Registry-Artefakt, kein fehlendes Image. Bevorzuge direkte Manifest-Checks.
• Rout führe bekannte Projekte auf ihre kanonische Registry. Eine winzige Zuordnung für die Projekte, die du pinnt, ist besser als generisches Raten.
• Behandle latest gesondert. latest ist ein beweglicher Tag; pinne für die Produktion unveränderliche Digests und lass den Validator das prüfen, was du tatsächlich ausführst.

Das Befriedigende war die Größe der Korrektur: Eine grobe Vermutung („MinIO fehlt!") entpuppte sich als fehlendes Feature („wir haben nie die richtige Registry gefragt"). Wir lieferten die Routing-Tabelle und den Manifest-Check, und derselbe Validator ging von „scheitert an jeder MinIO-Referenz" zu „bewacht 26 Image-Defaults stillschweigend". Die Tags waren die ganze Zeit echt – wir hatten nur die falsche Frage gestellt.