Am 1. April 2025 hat Docker neue Ratenbegrenzungen für Pulls für Docker Hub eingeführt, die sich erheblich auf CI/CD-Pipelines in der gesamten Branche auswirken können, einschließlich derer, die auf GitLab ausgeführt werden. Die gravierendste Änderung ist die Begrenzung auf 10 Pulls pro Stunde für nicht angemeldete Benutzer(innen).
Was ändert sich?
Ab dem 1. April 2025 hat Docker die folgenden Ratenbegrenzungen für Pulls durchgesetzt:
| Benutzertyp | Ratenbegrenzung für Pulls pro Stunde | Anzahl der öffentlichen Repositories | Anzahl der privaten Repositories |
|---|---|---|---|
| Business, Team, Pro (authentifiziert) | Unbegrenzt (angemessene Nutzung) | Unbegrenzt | Unbegrenzt |
| Persönlich (authentifiziert) | 100 | Unbegrenzt | Maximal 1 |
| Nicht angemeldete Benutzer(innen) | 10 pro IPv4-Adresse oder IPv6/64-Subnetz | Nicht zutreffend | Nicht zutreffend |
- Der Abhängigkeits-Proxy von GitLab pullt derzeit als nicht angemeldeter Benutzer von Docker Hub.
- Die meisten CI/CD-Pipelines, die den Abhängigkeits-Proxy nicht verwenden, pullen als nicht angemeldete Benutzer direkt von Docker Hub.
- Auf gehosteten Runnern für GitLab.com kann es vorkommen, dass sich mehrere Benutzer(innen) die gleiche IP-Adresse oder das gleiche Subnetz teilen. Somit unterliegen sie gemeinsam dieser Begrenzung.
Wie sich dies auf GitLab-Benutzer(innen) auswirkt
Auswirkungen auf direkte Pulls von Docker Hub
Wenn deine CI/CD-Pipelines Images direkt und ohne Authentifizierung von Docker Hub pullen, ist die Anzahl auf 10 Pulls pro Stunde und IP-Adresse begrenzt. Bei Pipelines, die häufig oder projektübergreifend mit derselben Runner-Infrastruktur ausgeführt werden, wird dieser Grenzwert schnell erreicht und es kommt zu Pipeline-Fehlern.
Auswirkungen auf den Abhängigkeits-Proxy von GitLab
Mit dem Abhängigkeits-Proxy von GitLab kannst du Docker-Images in GitLab zwischenspeichern, um Pipelines zu beschleunigen und externe Abhängigkeiten zu reduzieren. Die aktuelle Implementierung pullt allerdings als nicht angemeldeter Benutzer von Docker Hub. Das bedeutet, dass auch hier der Grenzwert von 10 Pulls pro Stunde gilt.
Auswirkungen auf gehostete Runner
Gehostete Runner auf GitLab.com verwenden den Pull-Through-Cache von Google Cloud. Dieser spiegelt häufig gepullte Images, sodass Ratenbegrenzungen vermieden werden. Images von Jobs, die in deiner .gitlab-ci.yml-Datei als image: oder services: definiert sind, sind von Ratenbegrenzungen nicht betroffen.
Etwas schwieriger wird es, wenn Images innerhalb der Runner-Umgebung gepullt werden. Der häufigste Anwendungsfall für das Pullen von Images während der Laufzeit eines Runners ist die Erstellung eines Images mit Docker-in-Docker oder Kaniko. In diesem Szenario wird das in deiner Dockerfile definierte Docker-Hub-Image direkt aus dem Docker Hub gepullt und ist wahrscheinlich von den Ratenbegrenzungen betroffen.
Wie GitLab reagiert
Wir arbeiten aktiv an Lösungen, um diese Herausforderungen zu bewältigen:
- Authentifizierung des Abhängigkeits-Proxy: Wir haben die Unterstützung für die Docker-Hub-Authentifizierung im GitLab-Abhängigkeits-Proxy hinzugefügt. Dadurch kann der Abhängigkeits-Proxy Images als angemeldeter Benutzer von Docker Hub pullen, wodurch die Grenzwerte erheblich erhöht werden.
- Aktualisierung der Dokumentation: Wir haben unsere Dokumentation (nur in englischer Sprache verfügbar) aktualisiert. Sie stellt jetzt eine klare Anleitung zur Konfiguration der Pipeline-Authentifizierung für Docker Hub zur Verfügung.
- Vorbereitung der internen Infrastruktur: Wir bereiten unsere interne Infrastruktur vor, um die Auswirkungen auf gehostete Runner für GitLab.com zu minimieren.
So kannst du dich vorbereiten
Option 1: Konfiguriere die Docker-Hub-Authentifizierung in deinen Pipelines
Für Pipelines, die direkt von Docker Hub pullen, kannst du die Authentifizierung so konfigurieren, dass deine Ratenbegrenzung auf 100 Pulls pro Stunde erhöht wird (mit einem kostenpflichtigen Docker-Hub-Abo ist sie sogar unbegrenzt).
Füge die Docker-Hub-Anmeldedaten zu den CI/CD-Variablen deines Projekts oder deiner Gruppe hinzu (nicht in deiner .gitlab-ci.yml-Datei). Ausführliche Anweisungen zur korrekten Einrichtung der CI/CD-Variable DOCKER_AUTH_CONFIG findest du in unserer Dokumentation zur Verwendung von Docker-Images (nur in englischer Sprache verfügbar).
Option 2: Verwende die GitLab-Container-Registry
Du kannst deine häufig verwendeten Docker-Images in deine GitLab-Container-Registry (nur in englischer Sprache verfügbar) übertragen. So musst du während der CI/CD-Ausführung nicht mehr von Docker Hub pullen:
- Pulle das Image von Docker Hub.
- Kennzeichne es für deine GitLab-Container-Registry.
- Pushe es in deine GitLab-Container-Registry.
- Aktualisiere deine Pipelines, dass sie das Image von der GitLab-Container-Registry abrufen.
docker pull busybox:latest
docker tag busybox:latest $CI_REGISTRY_IMAGE/busybox:latest
docker push $CI_REGISTRY_IMAGE/busybox:latest
In deiner .gitlab-ci.yml-Datei fügst du dann folgende Zeile hinzu:
image: $CI_REGISTRY_IMAGE/busybox:latest
Option 3: Verwende den GitLab-Abhängigkeits-Proxy
Mit dem Abhängigkeits-Proxy von GitLab kannst du Docker-Images zwischenspeichern und übertragen. Dies reduziert externe Abhängigkeiten und somit Probleme mit der Ratenbegrenzung.
Aktuelle Authentifizierungsoptionen:
- GitLab 17.10: Konfiguriere die Docker-Hub-Authentifizierung für den Abhängigkeits-Proxy mit der GraphQL API (nur in englischer Sprache verfügbar)
- GitLab 17.11: Verwende die neue UI-basierte Konfiguration in den Einstellungen deiner Gruppe (bereits auf GitLab.com verfügbar)
Sobald die Authentifizierung ordnungsgemäß konfiguriert ist, kannst du Folgendes tun:
- Konfiguriere die Docker-Hub-Anmeldeinformationen in den Einstellungen des Abhängigkeits-Proxys deiner Gruppe:
- Für GitLab 17.11+ (oder die aktuelle Version von GitLab.com): Navigiere zu den Einstellungen deiner Gruppe > Pakete und Registries > Abhängigkeits-Proxy.
- Für GitLab 17.10: Verwende die GraphQL-API, um die Authentifizierung zu konfigurieren.
- Aktualisiere deine Pipelines, sodass sie die Dependency-Proxy-URLs in deiner CI/CD-Konfiguration verwenden:
image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/busybox:latest
Option 4: Überlege dir, ein kostenpflichtiges Docker-Hub-Abonnement abzuschließen
Unternehmen, die Docker Hub intensiv nutzen, ist das Upgrade auf ein kostenpflichtiges Docker-Abonnement (Team oder Business) möglicherweise die einfachste Lösung, da es unbegrenzt viele Pulls ermöglicht.
Best Practices zur Reduzierung der Auswirkungen der Docker-Hub-Ratenbegrenzung
Unabhängig davon, welche Option du wählst, helfen dir diese Best Practices dabei, die Auswirkungen der Docker-Hub-Ratenbegrenzung zu minimieren:
- Verwende eindeutige Image-Tags anstelle von
latest, um unnötige Pulls zu vermeiden. - Konsolidiere deine Docker-Dateien, sodass sie projektübergreifend dieselben Basis-Images verwenden.
- Plane weniger kritische Pipelines so, dass sie außerhalb der Stoßzeiten ausgeführt werden.
- Verwende Caching effektiv, um zu vermeiden, dass dieselben Images wiederholt gepullt werden.
Hinweis: Gemäß der Dokumentation von Docker Hub wird der Counter für die Anzahl der Pulls erhöht, wenn das Image-Manifest gepullt wird, und nicht basierend auf der Image-Größe oder der Anzahl der Ebenen.
Zeitplan und nächste Schritte
Jetzt
- Implementiere die Authentifizierung für direkte Pulls von Docker Hub.
- Als Benutzer(in) von GitLab.com kannst du die Docker-Hub-Authentifizierung für den Abhängigkeits-Proxy bereits konfigurieren, indem du entweder:
- die GraphQL-API oder
- die Benutzeroberfläche in den Gruppeneinstellungen verwendest
- Benutzer(innen) von GitLab Self-Managed 17.10 können die Abhängigkeits-Proxy-Authentifizierung über die GraphQL-API konfigurieren.
1. April 2025
- Die Ratenbegrenzungen für Docker Hub treten in Kraft.
17. April 2025
- GitLab 17.11 wird mit UI-basierter Unterstützung für die Authentifizierung des Abhängigkeits-Proxy für Self-Managed-Instanzen veröffentlicht.
Du solltest rechtzeitig vor Ablauf der Frist am 1. April Maßnahmen ergreifen, um unerwartete Pipeline-Fehler zu vermeiden. Für die meisten Benutzer(innen) ist die Konfiguration des Abhängigkeits-Proxys mit der Docker-Hub-Authentifizierung die effizienteste Langzeitlösung.
Hast du Fragen oder benötigst du Hilfe bei der Implementierung? Sieh dir dieses Ticket an, wo unser Team aktiv Unterstützung bietet.