Docker レジストリミラーで、ビルドに必要なイメージを保持する

CI で同じ Docker イメージを繰り返しダウンロードしているなら、Docker レジストリミラーを使って取得済みのイメージを共有することで、通信量や待ち時間を削減できます。特に、ジョブごとに新しい実行環境を用意するチームでは、同じレイヤーを何度も取得する負担が積み重なります。

ミラーの導入を考えるきっかけが、突然のビルド失敗であることもあります。開発者の PC では動くのに、新しい CI ランナーでは失敗する。調べてみると、配布元からイメージが削除され、PC に残っていたローカルキャッシュだけがビルドを支えていた、というケースです。

ミラーがこうした問題に役立つかどうかは、保存したイメージの扱いによって変わります。配布元の更新に追従するのか、古いキャッシュを自動で削除するのか、最初に取得した内容を保持するのか。過去のリリースを後から再ビルドする必要があるなら、取得速度に加えて、更新と保持の方針を確認する必要があります。

Docker レジストリミラーの仕組み

Docker レジストリミラーは、上流のレジストリからイメージを取得し、後のリクエストでも利用できるように保存します。要求されたイメージを初回のリクエスト時に取得して保存する方式を、プルスルーキャッシュと呼びます。取得元が Docker Hub であるミラーは、Docker Hub ミラーとも呼ばれます。

ジョブ終了後に破棄される CI ランナーでは、ローカルのイメージキャッシュも失われます。共有の Docker イメージキャッシュを使えば、あるランナーが取得したレイヤーを、別のランナーでも利用できます。

こうした Docker レジストリキャッシュの効果は、ビルドの頻度やイメージの大きさによって異なります。同じ大きなベースイメージを使うジョブが多いほど、重複するダウンロードを減らす効果が期待できます。

ダウンロード量、取得制限、配布元の障害

複数のランナーが同じ公開 IP アドレスを使う環境では、Docker Hub の取得制限も確認が必要です。Docker の公式資料では、未認証の利用は IPv4 アドレスまたは IPv6 の /64 サブネットごとに6時間で100回、認証済みの Personal アカウントは6時間で200回とされています。認証済みの Pro、Team、Business アカウントには通常のプル回数の上限はありませんが、フェアユースや別途設けられた不正利用防止の制限は適用されます。

共有キャッシュは、同じイメージを繰り返し上流から取得する負担を減らします。多数の CI ジョブが同じイメージを利用する環境では、通信量の削減に加え、イメージの取得にかかる待ち時間の短縮にもつながります。

配布元に障害が起きたときも、保存済みのイメージをミラーから取得できる場合があります。ただし、必要な内容が保持されていることと、上流に接続できなくても配信できることが条件です。可用性を目的に導入するなら、この動作を事前に確認しておく必要があります。

Dockerfile が同じでも、イメージは変わる

次の指定は Ubuntu のリリースを特定していますが、イメージの内容まで固定するものではありません。

FROM ubuntu:24.04

同じタグに新しいイメージが割り当てられると、Dockerfile を変更していなくても、数か月前と今日のビルドでは異なるベースイメージを使う可能性があります。

ある開発者は古いキャッシュを使い、別の開発者は更新後のイメージを使い、CI は毎回新しく取得する。こうした違いがあると、不具合の原因を調べる前に、環境の差を特定しなければなりません。

セキュリティ修正を取り込むためにベースイメージを更新することは、通常の保守作業です。ただし、上流でのタグの更新によって使用するイメージが変わると、アプリケーションのリポジトリには、その更新を確認するためのプルリクエストや、元に戻すための変更履歴が残りません。

キャッシュの更新と保持の方針を確認する

Docker の公式資料で説明されているプルスルーキャッシュは、タグを指定したリクエストに対して上流の更新を確認し、必要に応じて新しい内容を取得します。また、ディスク容量を管理するため、古いキャッシュを定期的に削除します。これは、この実装についての説明であり、すべてのミラーが同じ動作をするわけではありません。

たとえば、3月のリリースで使った my-image:1.4 の内容を、配布元が6月に差し替えたとします。上流の更新に追従するミラーでは、3月のリリースを再ビルドするときにも、新しい内容が使われる可能性があります。

また、保存済みのイメージがキャッシュから削除されれば、次の取得には再び上流へのアクセスが必要です。その時点で配布元からも削除されていれば、どちらからも取得できません。

過去のビルド環境を維持するには、キャッシュの有無だけでなく、何が更新され、何が保持されるのかを把握する必要があります。

StableBuild が保持するイメージ

StableBuild の Docker ミラーは、タグを初めてサービス経由で取得したときのイメージを保持します。その後は、上流で同じタグの内容が変わっても、保存済みのイメージを返します。公式ドキュメントでは、キャッシュしたイメージを自動で削除しないと説明されています。

更新する場合は、利用者がダッシュボードで該当するキャッシュ済みタグを削除し、次のプルで上流から再取得できます。チームが更新のタイミングを管理できるため、検証の手順に合わせて更新を進められます。

こうしたイミュータブルな Docker ミラーを使う場合も、脆弱性の評価や更新の検証は必要です。古いイメージを保持しても、その中のパッケージが安全になるわけではありません。保持することで、移行先の検証を進めながら、既存の環境も再構築できる状態を維持できます。

配布元からイメージが消えた事例

2026年9月、Docker Hub から minio/minio と minio/mc のリポジトリが消え、これらを参照していたビルドに影響が出ました。StableBuild 自身も、MinIO を Docker Hub から直接取得していたサブシステムで、スモークテストが失敗しました。一方、あらかじめ StableBuild 経由でイメージを取得していた顧客は、保存済みのコピーを引き続き利用できました。

Docker Hub から取得できなくなった当初は、必要な過去の MinIO イメージを Quay から取得できました。しかし、2026年10月2日には、同じリリースの匿名での取得が Quay でも認証エラーになりました。イメージが削除されたかどうかは確認できませんが、配布元を切り替えても、その後の取得が保証されるわけではありません。StableBuild では、このリリースを事前にキャッシュしていたため、保存済みの同じイメージを引き続き取得できました。

出典：Quay からの MinIO 取得に関する StableBuild の続報

NVIDIA CUDA のコンテナイメージにも、サポート終了に伴うタグの削除方針があります。CUDA のリリース、イメージの種類、OS を細かく指定していても、配布が終了すれば取得できなくなる可能性があります。

ミラーが役立つのは、必要なイメージを事前に取得し、その内容を保持している場合です。取得可能なコピーがなくなった後でミラーを導入しても、保存していなかったイメージを復元することはできません。

ダイジェストによる固定と、イメージの保持

SHA256 ダイジェストは、イメージの内容を正確に識別するために使われます。GitHub Container Registry の公式資料でも、同じイメージを確実に指定する方法として、ダイジェストを使ったプルが案内されています。参照先が変わり得るタグに依存せず、取得する内容を指定できます。

ただし、ダイジェストを記録しても、レジストリがその内容を配信し続けるとは限りません。StableBuild はダイジェストによるプルにも対応していますが、保存する前に上流から削除されたイメージを復元することはできません。

過去のリリースを保守するには、取得する内容を正確に指定することと、その内容を引き続き取得できることの両方が必要です。

また、依存イメージの保持だけで、ビルド結果が完全に一致することを保証できるわけではありません。再現可能な Docker ビルドには、コンパイラ、タイムスタンプ、環境変数など、ほかの入力や処理の管理にも関わります。

プライベートレジストリとの使い分け

プライベート Docker レジストリは、一般に、自社でビルド・公開するイメージを保管し、開発者やデプロイシステムからのアクセスを管理するために使用致します。外部のイメージを取得し、自社で管理するレジストリにコピーしておく方法もあります。Docker の公式資料でも、ミラーの代替としてこの方法が紹介されています。

依存するイメージが少数で明確なら、手動でコピーを管理する方法で十分な場合があります。ただし、新たに使い始めたイメージも保存対象に加える必要があります。プルスルーミラーはリクエストに応じて取得・保存するため、対象が増えてもビルドの運用に組み込みやすい方式です。

自社のアプリケーションにはプライベートレジストリ、外部の依存イメージにはミラーという併用も可能です。どちらの場合も、保持の方針と更新手順を決めておく必要があります。

自社でミラーを運用する場合

Docker のレジストリは、Docker Hub を取得元とするプルスルーキャッシュとして構成できます。

ミラーサーバーを用意したうえで、クライアント側の daemon.json に次の設定を追加し、設定を反映させると、そのミラーを利用できます。これはクライアントの接続先設定であり、ミラーサーバー自体の構築は別途必要です。

{
  "registry-mirrors": [
    "https://mirror.example.com"
  ]
}

運用では、ストレージ、認証、監視、セキュリティ、可用性をチームが管理します。数年にわたってイメージを保持するなら、保存方針に加え、インフラ障害からデータを復旧する方法も必要です。

自社運用を支える人員や仕組みがある組織には、有効な選択肢です。一方、複数のサービスを保守するプロダクトチームにとっては、管理対象が一つ増えることになります。ホスティング費用や取得速度だけでなく、継続的な運用にかかる負担も比較する必要があります。

既存のビルドを StableBuild に接続する

StableBuild は、Docker Hub、GitHub Container Registry、NVIDIA NGC、Quay の公開イメージに対応したマネージドミラーを提供しています。現時点では、プライベートリポジトリには対応していません。

Docker Hub のイメージは、次のように StableBuild のミラードメインを付けて取得できます。your-domain は、利用するミラーのドメインに置き換えてください。

FROM your-domain.dockermirror.stablebuild.com/ubuntu:24.04

Dockerfile を変更しにくい場合は、Docker デーモンのレジストリミラーとして設定する方法もあります。この設定は Docker Hub 向けです。他の対応レジストリを利用するときは、それぞれの取得元を指定する方法を公式ドキュメントで確認してください。

StableBuild は、イメージで提供されている各アーキテクチャの内容を保存します。開発者の PC が ARM、デプロイ先が x86 であるなど、異なるアーキテクチャを使う環境でも重要な機能です。

ただし、古い v1/schema1 形式ではメインのマニフェストのみが保存され、レイヤーは保存されません。また、5GB を超えるレイヤーは非同期で保存されます。対象の形式やサイズによっては、保存の完了状況も確認する必要があります。

導入前に確認しておきたいこと

ミラーを選ぶ際は、次の点を確認すると、自社の用途に合うかを判断しやすくなります。

• 保存済みタグは上流の更新に追従するか、最初に取得した内容を保持するか
• イメージが自動で削除されることはあるか
• 上流の障害やイメージの削除後も、保存済みの内容を取得できるか
• 対応するレジストリ、アーキテクチャ、イメージ形式は何か
• プル回数、ストレージ、通信量にどのような制限があるか
• 誰が基盤を運用し、保存データを保護するか
• 保持しているイメージを更新するには、どのような手順が必要か

重複するダウンロードの削減と、過去のリリースを保守できる状態の維持では、必要な運用方針が異なります。自社の目的を明確にしたうえで、保存と更新の動作を確かめてください。

必要なイメージを取得できるうちに試す

まずは、プロジェクトで使っているイメージを一つ選び、ローカルキャッシュのない環境で取得してみてください。普段の PC でビルドが成功するだけでは、新しい CI ランナーでも同じイメージを取得できるかは分かりません。

StableBuild の無料 Community プランでは、プランに定められた通信量とストレージの範囲内で、依存イメージの保持を試せます。ミラー経由でイメージを保存し、新しい環境でもそのコピーを取得してビルドできることを確認してください。

詳しくは、StableBuild の Docker ミラーのドキュメントと料金ページをご覧ください。