今すぐ対策を：Docker Hubのレート制限がGitLab CI/CDに与える影響

2025年4月1日より、DockerはDocker Hubに新たなプルレート制限を導入します。これは、GitLabで稼働しているものを含め、業界全体のCI/CDパイプラインに大きな影響を及ぼす可能性があります。最も大きな変更点は、未認証ユーザーに対して1時間あたり10回までというプル制限が設けられることです。

変更点

4月1日から、Dockerは以下のプルレート制限を適用します。

ユーザータイプ	1時間あたりのプルレート制限	パブリックリポジトリ数	プライベートリポジトリ数
Business、Team、Pro（認証済）	無制限（フェアユース）	無制限	無制限
Personal（認証済）	100	無制限	最大1つ
未認証ユーザー	IPv4アドレスまたはIPv6/64サブネットごとに1時間あたり10回	該当なし	該当なし

この変更が重要な理由は以下のとおりです。

• GitLabの依存プロキシは現在、未認証ユーザーとしてDocker Hubからプルしています。
• 依存プロキシを使用していないほとんどのCI/CDパイプラインは、未認証ユーザーとしてDocker Hubから直接プルしています。
• GitLab.comのホステッドランナーでは、複数のユーザーが同じIPアドレスやサブネットを共有することがあり、全体がこの制限の対象になります。

GitLabユーザーへの影響

Docker Hubからの直接プルに関する影響

CI/CDパイプラインがDocker Hubから認証なしで直接イメージをプルしている場合、IPアドレスごとに1時間あたり10回の制限が適用されます。頻繁に実行されるパイプラインや、同じランナーインフラを共有している複数プロジェクトでは、この制限にすぐに達してしまい、パイプラインの失敗が発生する可能性があります。

GitLab依存プロキシへの影響

GitLabの依存プロキシ機能は、DockerイメージをGitLab内にキャッシュすることでパイプラインの高速化や外部依存関係の削減を実現します。ただし、現在の実装では未認証ユーザーとしてDocker Hubからプルしているため、これも1時間あたり10回という制限の対象になります。

ホステッドランナーへの影響

GitLab.comのホステッドランナーでは、Google Cloudのプルスルーキャッシュを使用しています。これにより、よく使われるイメージがミラーされ、レート制限を回避できます。.gitlab-ci.ymlファイル内でimage:またはservices:として定義されたジョブイメージは、レート制限の影響を受けません。

一方で、ランナー環境内でイメージをプルするケースではやや複雑になります。ランナー実行中にイメージをプルする最も一般的なユースケースは、Docker-in-DockerやKanikoを使ってイメージをビルドする場合です。このシナリオでは、Dockerfileで指定されたDocker Hubのイメージが直接プルされるため、レート制限の影響を受ける可能性があります。

GitLabの対応

この問題を緩和するため、GitLabでは以下の対応を進めています。

• 依存プロキシの認証： GitLabの依存プロキシ機能にDocker Hubの認証のサポートを追加しました。これにより、依存プロキシは認証済みユーザーとしてDocker Hubからイメージをプルできるようになり、レート制限が大幅に緩和されます。
• ドキュメントの更新： Docker Hubのパイプライン認証の設定に関する明確なガイダンスを提供するために、ドキュメントを更新しました。
• 内部インフラの整備： GitLab.comのホステッドランナーへの影響を最小限にするため、内部インフラを整備中です。

ユーザー側でできる対策

オプション1：パイプラインでDocker Hub認証を設定する

Docker Hubから直接プルしているパイプラインでは、認証を設定することでレート制限を1時間あたり100回（または有料プランなら無制限）まで増やせます。

Docker Hubの認証情報をプロジェクトまたはグループのCI/CD変数に追加してください（.gitlab-ci.ymlには追加しないでください）。DOCKER_AUTH_CONFIG CI/CD変数の正しい設定方法については、Dockerイメージの使用に関するドキュメントを参照してください。

オプション2：GitLabのコンテナレジストリを使用する

頻繁に使用するDockerイメージをGitLabのコンテナレジストリにプッシュすることで、CI/CDの実行中にDocker Hubからプルする必要がなくなります。

1. Docker Hubからイメージをプルします
2. GitLabコンテナレジストリにタグ付けします
3. GitLabコンテナレジストリにプッシュします
4. パイプラインをGitLabコンテナレジストリからプルするよう更新します

docker pull busybox:latest
docker tag busybox:latest $CI_REGISTRY_IMAGE/busybox:latest
docker push $CI_REGISTRY_IMAGE/busybox:latest

それから、.gitlab-ci.ymlで以下のように記述します。

image: $CI_REGISTRY_IMAGE/busybox:latest

オプション3：GitLabの依存プロキシを使用する

GitLabの依存プロキシ機能を使うことで、Dockerイメージをキャッシュしてプロキシ経由で取得できるため、外部依存関係を減らし、レート制限の問題を軽減できます。

現在の認証オプションは以下のとおりです。

• GitLab 17.10：GraphQL APIを使って、依存プロキシ用のDocker Hub認証を設定
• GitLab 17.11：グループ設定に新しく追加されたUIベースの設定を使用（GitLab.comでは既に利用可能）

認証が正しく設定されると、以下の操作が可能になります。

1. グループの依存プロキシ設定でDocker Hubの認証情報を設定する

• GitLab 17.11以降（またはGitLab.com）：グループ設定 > パッケージとレジストリ > 依存プロキシで設定
• GitLab 17.10：GraphQL APIで認証を設定

2. CI/CD設定で依存プロキシURLを使用するよう、パイプラインを更新する
   image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/busybox:latest

オプション4：Docker Hubの有料プランを検討する

Docker Hubの利用が多い組織の場合は、プル回数が無制限の有料Dockerサブスクリプション（TeamまたはBusiness）へのアップグレードが最も簡単な解決策となる場合があります。

Docker Hubのレート制限による影響を減らすベストプラクティス

どのオプションを選ぶ場合でも、Docker Hubのレート制限の影響を最小限に抑えるために、以下のベストプラクティスを参考にしてください。

• latestタグではなく、特定のバージョンタグを使用して不要なプルを避ける
• Dockerファイルを統合し、同じベースイメージを複数のプロジェクトで使い回す
• あまり重要でないパイプラインは、ピーク時間を避けて実行するようスケジュールする
• キャッシュを有効活用し、同じイメージを繰り返しプルするのを避ける

注： Docker Hubのドキュメントによると、プル回数はイメージのサイズやレイヤー数ではなく、manifestを取得した時点で1回とカウントされます。

スケジュールと今後の流れ

現在

• Docker Hubからの直接プルに認証を実装します
• GitLab.comユーザーは以下のいずれかで依存プロキシ認証を設定できます
  • GraphQL API
  • グループ設定のUI
  • Self-ManagedのGitLab 17.10ユーザーはGraphQL APIを使用して依存プロキシ認証を設定できます

2025年4月1日

• Docker Hubのレート制限が始まります

2025年4月17日

• Self-Managedインスタンス向けの依存プロキシ認証機能をUIに追加したGitLab 17.11がリリースされます

パイプラインの予期せぬ失敗を回避するために、可能な限り速やかに対応することをおすすめします。多くのユーザーにとっては、Docker Hub認証を使用して依存プロキシを設定することが最も効率的な長期的解決策となります。

ご質問がある場合や、実装に関してサポートが必要な場合は、こちらのイシューをご覧ください。GitLabのチームによる対応が確認できます。

監修：川瀬 洋平 @ykawase （GitLab合同会社 カスタマーサクセス本部 シニアカスタマーサクセスマネージャー）