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のプルスルーキャッシュ](https://cloud.google.com/artifact-registry/docs/pull-cached-dockerhub-images?hl=ja)を使用しています。これにより、よく使われるイメージがミラーされ、レート制限を回避できます。`.gitlab-ci.yml`ファイル内で`image:`または`services:`として定義されたジョブイメージは、レート制限の影響を受けません。
一方で、ランナー環境内でイメージをプルするケースではやや複雑になります。ランナー実行中にイメージをプルする最も一般的なユースケースは、Docker-in-DockerやKanikoを使ってイメージをビルドする場合です。このシナリオでは、`Dockerfile`で指定されたDocker Hubのイメージが直接プルされるため、レート制限の影響を受ける可能性があります。
## GitLabの対応
この問題を緩和するため、GitLabでは以下の対応を進めています。
* **依存プロキシの認証：** GitLabの[依存プロキシ機能](https://gitlab.com/gitlab-org/gitlab/-/issues/331741)にDocker Hubの認証のサポートを追加しました。これにより、依存プロキシは認証済みユーザーとしてDocker Hubからイメージをプルできるようになり、レート制限が大幅に緩和されます。
* **ドキュメントの更新：** Docker Hubのパイプライン認証の設定に関する明確なガイダンスを提供するために、[ドキュメント](https://docs.gitlab.com/user/packages/dependency_proxy/#configure-credentials)を更新しました。
* **内部インフラの整備：** GitLab.comのホステッドランナーへの影響を最小限にするため、内部インフラを整備中です。
## ユーザー側でできる対策
**オプション1：パイプラインでDocker Hub認証を設定する**
Docker Hubから直接プルしているパイプラインでは、認証を設定することでレート制限を1時間あたり100回（または有料プランなら無制限）まで増やせます。
Docker Hubの認証情報をプロジェクトまたはグループのCI/CD変数に追加してください（`.gitlab-ci.yml`には追加しないでください）。`DOCKER_AUTH_CONFIG` CI/CD変数の正しい設定方法については、[Dockerイメージの使用に関するドキュメント](https://docs.gitlab.com/ci/docker/using_docker_images/#use-statically-defined-credentials)を参照してください。
**オプション2：GitLabのコンテナレジストリを使用する**
頻繁に使用するDockerイメージを[GitLabのコンテナレジストリ](https://docs.gitlab.com/user/packages/container_registry/)にプッシュすることで、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](https://docs.gitlab.com/user/packages/dependency_proxy/#configure-credentials-using-the-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の[ドキュメント](https://docs.docker.com/docker-hub/usage/pulls/#pull-definition)によると、プル回数はイメージのサイズやレイヤー数ではなく、manifestを取得した時点で1回とカウントされます。
## スケジュールと今後の流れ
**現在**
* Docker Hubからの直接プルに認証を実装します
* GitLab.comユーザーは以下のいずれかで依存プロキシ認証を設定できます
* GraphQL API
* グループ設定のUI
* Self-ManagedのGitLab 17.10ユーザーはGraphQL APIを使用して依存プロキシ認証を設定できます
2025年4月1日
2025年4月17日
- Self-Managedインスタンス向けの依存プロキシ認証機能をUIに追加したGitLab 17.11がリリースされます
パイプラインの予期せぬ失敗を回避するために、可能な限り速やかに対応することをおすすめします。多くのユーザーにとっては、Docker Hub認証を使用して依存プロキシを設定することが最も効率的な長期的解決策となります。
ご質問がある場合や、実装に関してサポートが必要な場合は、こちらのイシューをご覧ください。GitLabのチームによる対応が確認できます。
監修：川瀬 洋平 @ykawase
（GitLab合同会社 カスタマーサクセス本部 シニアカスタマーサクセスマネージャー）
