Docker pull が toomanyrequests で失敗する（Docker Hub レート制限）

要約

Error response from daemon: toomanyrequests: You have reached your pull rate limit. は Docker Hub の 匿名 / 無料アカウント向けレート制限 に達した状態。docker login で認証 pull にすれば上限が引き上がり、ミラーレジストリを併用すれば共有 IP の枯渇も回避できる。

よくある原因

1. 匿名 pull の上限: 匿名は IP あたりの pull 回数が抑えられている（公式ドキュメント 参照）
2. 共有 IP の枯渇: 社内 NAT や CI ランナーで全員が同じ送信元 IP として扱われ、個々人の体感より早く上限到達
3. 未ログイン: ローカル / CI で docker login を打っておらず、無料アカウントの上限すら使えていない
4. キャッシュ未活用: CI が毎回まっさらな環境で pull し直し、Docker Hub への往復回数が増えている

解決策

1. 認証 pull に切り替える

docker login -u <username>
docker pull node:20

CI なら secrets に PAT を入れ、ジョブ冒頭で docker login を実行する。
匿名上限の縛りが消えてアカウント単位の上限になる。

2. ミラーレジストリを使う

docker pull mirror.gcr.io/library/node:20         # Google
docker pull public.ecr.aws/docker/library/node:20 # AWS Public ECR

base image を Docker Hub 以外から取得すれば、Docker Hub の上限を消費しない。/etc/docker/daemon.json の registry-mirrors を設定すれば透過的に切り替えられる。

3. レイヤキャッシュを CI に効かせる

# GitHub Actions の例 (docker/build-push-action)
- uses: docker/build-push-action@v5
  with:
    cache-from: type=gha
    cache-to: type=gha,mode=max

ビルドのたびにフル pull せずに済む。buildx の --cache-from --cache-to でも同じことができる。

4. 社内レジストリに再配布

頻繁に使う base image は 社内 / プロジェクト専用レジストリ に push しておき、開発機・CI ともそちらを参照する。
Docker Hub の上限を分散でき、ネットワーク切断時も pull が継続できる。