メインコンテンツまでスキップ

第17章：buildx入門：キャッシュを持ち運ぶ 🎒➡️🧰⚡️

この章のゴールはシンプルです👇 「ローカルで積んだキャッシュを、別PC・別環境・CIでも使い回して、ビルド待ちを激減させる」 😆✨ CIみたいに“毎回まっさら”になりがちな環境では、外部キャッシュがほぼ必須級になります。(Docker Documentation)

1) まずは超ざっくり図で理解しよ 🧠🖼️​

ビルドのキャッシュって、ざっくりこう👇

  • Dockerfileの各ステップで「結果」が溜まる📦
  • 次回は「同じ条件なら再利用」できて速い⚡️
  • でも別環境に行くと、その“貯金”が無いことが多い🥲
  • そこで buildx の --cache-to / --cache-from で、キャッシュを外に出して持ち運ぶ🎒✨ (Docker Documentation)
[初回]    build ──▶ キャッシュが貯まる
            │
            ├─▶ (cache-to)  外部へ保存  🎒
            │
[次回]    build ──▶ (cache-from) 外部から読み込み → 爆速 ⚡️

2) --cache-to / --cache-from って何？🤔​

docker buildx build は BuildKit でビルドしてくれるコマンドで、 --cache-from が「読み込み」、--cache-to が「書き出し」です。(Docker Documentation)

対応してる保存先（backend / type）は代表的にこんな感じ👇

3) 重要：buildxには「ビルダー（driver）」がある 🚗💨​

ここが最初の分かれ道です👇

  • 既定の docker driver は、条件によって使えるキャッシュ方式が制限されます → inline/local/registry/gha を使うには containerd image store が有効である必要があります。(Docker Documentation)
  • 一方、docker-container driver は、BuildKitを専用コンテナで動かして、キャッシュ状態をボリュームに保持できるのが強い💪(Docker Documentation)
  • さらに registry キャッシュは 既定の docker driver では非対応 と明記されています（ここで詰まりがち！）(Docker Documentation)

3.1 containerd image store（Docker Desktop）🧰​

Docker Desktop では、containerd image store をONにすると build の幅が広がります。 4.34以降は「クリーンインストール/初期化」だと既定でON、アップグレード組は手動ONが必要な場合があります。(Docker Documentation)

4) ハンズオン①：まずは local キャッシュで体感しよう 🏃‍♂️💨​

local は「キャッシュをフォルダに保存する」方式で、構造はOCI形式レイアウトです。(Docker Documentation) 公式の基本形はこれ👇(Docker Documentation)

docker buildx build --push -t <registry>/<image> \
  --cache-to type=local,dest=path/to/local/dir \
  --cache-from type=local,src=path/to/local/dir .

手元で試すなら --load（ローカルに読み込み）でOK🙆‍♂️ ※フォルダは .gitignore 推奨（巨大化しやすい）📁💦

例：リポジトリ直下に .buildx-cache を作る

docker buildx build -t myapp:dev \
  --cache-to type=local,dest=.buildx-cache,mode=max \
  --cache-from type=local,src=.buildx-cache \
  --load .

mode=max って何？🧠​

  • mode=min（既定）：最終成果物に入るレイヤ中心＝小さめ📦
  • mode=max：途中ステップも含めて広く取る＝当たりやすい⚡️（ただし大きめ）(Docker Documentation)

5) ハンズオン②：registry キャッシュで「別PC/CI」へ持ち運ぶ 🛰️📦​

registry は「キャッシュを専用の別イメージとしてプッシュする」方式。 inlineより柔軟で、マルチステージにも強いと説明されています。(Docker Documentation)

基本形👇(Docker Documentation)

docker buildx build --push -t <registry>/<image> \
  --cache-to type=registry,ref=<registry>/<cache-image>,mode=max \
  --cache-from type=registry,ref=<registry>/<cache-image> .

⚠️ハマりどころ（超重要）​

  • キャッシュ用 ref は、成果物イメージと同じ場所にしない（タグを分ける等）と明記されています。(Docker Documentation)

    • 例：myapp:latest と myapp:buildcache みたいに分ける👍

  • そして registry キャッシュは既定の docker driver では非対応。(Docker Documentation) → そういう時は docker-container のビルダーを作って使うのが定番です👇(Docker Documentation)

ビルダー作成（例）

docker buildx create --name container \
  --driver=docker-container \
  --use --bootstrap

docker-container driver は BuildKitの状態（キャッシュなど）を専用ボリュームに保持できる、と説明されています。(Docker Documentation)

6) ハンズオン③：GitHub Actionsなら type=gha がラク 🤖⚙️​

GitHub Actions キャッシュに保存する gha backend の基本形👇(Docker Documentation)

docker buildx build --push -t <registry>/<image> \
  --cache-to type=gha \
  --cache-from type=gha .

さらに、docker/build-push-action を使うなら url と token は自動で入るので、設定はほぼ cache-to/cache-from だけでOKです。(Docker Documentation)

例（GitHub Actions / build-push-action v6）

- name: Build and push
  uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: "<registry>/<image>:latest"
    cache-from: type=gha
    cache-to: type=gha,mode=max

あと、GitHub のキャッシュAPIは v2 への移行が前提になっていて、古い仕組みだとエラーになる注意書きがあります（今やるなら新しめの Action を使えばだいたいOK）。(Docker Documentation)

7) 「どれを選ぶ？」3秒で決める早見表 🧭✨​

8) 🧪ミニ演習：あなたの「キャッシュ設計図」を描こう ✍️🗺️​

演習A（体感コース）⚡️​

  1. local で .buildx-cache を作る
  2. 同じビルドを2回やって、2回目が速いのを確認😆
  3. mode=min と mode=max を切り替えて、サイズと速さの違いをメモ📝(Docker Documentation)

演習B（持ち運びコース）🎒​

  1. registry キャッシュを :buildcache みたいなタグで分ける（成果物と同じにしない）(Docker Documentation)
  2. docker-container ビルダーを作ってビルド＆push(Docker Documentation)
  3. 別環境（またはCI）で --cache-from して、速度差を見る👀✨

9) 🤖AI活用（コピペでOK）プロンプト集 🧠💬​

9.1 キャッシュ戦略を決めてもらう 🧭​

「次の要件で buildx キャッシュ戦略を提案して。local/registry/gha どれがいい？ その理由と、具体的なコマンド例も。要件：①CIはGitHub Actions ②本番イメージはレジストリにpush ③マルチステージ ④依存が重い」

9.2 “効いてない”原因探し 🔍​

「この docker buildx build コマンド（とDockerfile）でキャッシュが効かない理由を3つ挙げて。--cache-to/--cache-from の指定、driver問題、mode、cache保存先の衝突の観点でチェックして、修正案も出して」

9.3 PRレビュー用（短く強い）🧑‍⚖️​

「この変更でキャッシュヒット率は上がる？下がる？理由を“Dockerfileの変更頻度が高い/低い”の観点でコメント文にして」

10) ここまでのまとめ 🏁✨​

  • buildx の --cache-to / --cache-from でキャッシュを外へ出して持ち運べる🎒(Docker Documentation)
  • local / registry / gha が最頻出の3択📦🛰️🤖(Docker Documentation)
  • registry は driver で詰まりがちなので、docker-container ビルダーの存在を覚えると勝ち💪(Docker Documentation)
  • mode=max は当たりやすいけどデカくなる。まずは測って決める📊(Docker Documentation)

次の章（第18章）で「マルチステージで速く＆軽く」をやると、この章のキャッシュ持ち運びがさらに効いて気持ちよくなりますよ😆🔥