Skip to main content

第16章：BuildKitの必殺技②：キャッシュ“保存先”の種類 🧳✨

この章はひとことで言うと👇 **「せっかく作ったビルドキャッシュ、どこに保存して、どう持ち運ぶ？」**を理解する回です 😆⚡️

1) まず超重要：キャッシュには“2系統”あるよ 🧠🧱​

BuildKitのキャッシュは、大きくこう分かれます👇

  • 🧱 レイヤキャッシュ：Dockerfileの各ステップ（RUN/COPYなど）の結果
  • 🧺 キャッシュマウント：RUN --mount=type=cache で溜めたダウンロード等のキャッシュ（第12章で触れたやつ）

この第16章で主に扱うのは 🧱レイヤキャッシュを“外に保存する”話 だよ ✅ （CIが速くなるかどうかは、ここが超効く！）🚀

2) 図でわかる：内部キャッシュ vs 外部キャッシュ 🗺️​

イメージしやすく描くとこんな感じ👇

(あなたのPC / CIマシン)
   │
   │  docker buildx build
   ▼
[BuildKitの内部キャッシュ]  ← 放っておいても使われる（いつか消える/CIでは残りにくい）
   │
   ├─ export（--cache-to）→  [外部キャッシュ保存先]  ← 持ち運び・共有できる！
   └─ import（--cache-from）← ここから再利用して爆速化🔥

外部キャッシュは 「保存（export）も、読み込み（import）も明示的に指定」 が必要です。 内部キャッシュは常に有効だけど、外部キャッシュは 自分で出し入れする感じ！📦✨ (Docker Documentation)

3) “保存先”の種類まとめ（これが第16章の主役）🏆​

BuildKit（buildx）には、代表的にこの保存先があります👇

A. 内部キャッシュ（デフォルト）🏠​

  • 何もしなくても効く
  • でも CIみたいに毎回まっさらだと、ほぼ残らないことが多い😇
  • “速くする努力”をCIへ持ち越すには、次の外部キャッシュが必要になる場面が多いよ (Docker Documentation)

B. inline（成果物イメージに埋め込み）📎​

  • 一番カンタンに外部キャッシュ化できる方式
  • 「どうせイメージをpushする」なら始めやすい👍
  • ただし、キャッシュ情報が成果物側に混ざるので、専用キャッシュより効率で負けることも（用途次第） (Docker Documentation)

C. local（ローカルのディレクトリに保存）🗂️​

  • キャッシュを フォルダとして保存するシンプル型
  • 「まず試す」「自分のPCで持ち回す」「共有ストレージに置く」など柔軟
  • 内部形式はOCI image layout（フォルダ構造がそうなってる） (Docker Documentation)

D. registry（レジストリにキャッシュ専用イメージとして保存）🏢📦​

  • チーム共有・CI共有の本命🔥
  • ref=... で キャッシュ用の参照（別イメージ） を作って保存できる
  • 圧縮（zstd等）やOCIメディアタイプなど、細かい最適化もできる (Docker Documentation)

E. gha（GitHub Actionsのキャッシュに保存）🐙⚙️​

  • GitHub Actions上での推奨キャッシュとして案内されてる方式（制限はGitHub側のルールに従う） (Docker Documentation)
  • ただし注意：キャッシュマウント（--mount=type=cache）は、GHAキャッシュにそのまま残らない ことがある（回避策あり） (Docker Documentation)

F. s3 / azblob（クラウドに保存：一部experimental）☁️​

  • 使えるけど、現場ではまず registry / gha が先に候補になりがち
  • buildxのCLIヘルプにも “importできる” 種類として出てくる (Docker Documentation)

4) 使い分け：どれ選べばいいの？🤔➡️😆​

迷ったらこの優先順位が安全です👇

  • ローカル開発だけ速くしたい → まず 内部キャッシュ + Dockerfile最適化（第7〜15章）
  • PC内でも“持ち越したい”（ブランチ切り替え多い等） → local 🗂️
  • チームやCIで共有したい → registry 🏢（強い）
  • GitHub Actionsが主戦場 → gha 🐙（まずこれ）
  • pushする成果物イメージが常にある & とにかく簡単に → inline 📎

5) 実践①：まずはローカルに書き出して体感しよう 🧪⚡️​

✅ コマンドの形（まず型を覚える）​

  • 保存（export）：--cache-to ...
  • 読み込み（import）：--cache-from ... (Docker Documentation)

✅ 例：localキャッシュで“2回目爆速”を作る（Node/TS想定）🗂️​

## 1回目：キャッシュを書き出す
docker buildx build ^
  -t myapp:dev ^
  --cache-to type=local,dest=.buildx-cache,mode=max ^
  --load ^
  .

## 2回目：キャッシュを読み込んでビルド（速くなる！）
docker buildx build ^
  -t myapp:dev ^
  --cache-from type=local,src=.buildx-cache ^
  --cache-to   type=local,dest=.buildx-cache,mode=max ^
  --load ^
  .

ポイント👇

  • 2回目も --cache-to を付けて更新していくと、キャッシュが育っていく🌱
  • mode=max は中間レイヤまで広く保存したい時に便利（まずは max でOK）🧠 (Docker Documentation)

6) 実践②：レジストリに“キャッシュ専用ref”を置く（CI最強）🏢🔥​

docker buildx build ^
  -t ghcr.io/OWNER/myapp:latest ^
  --push ^
  --cache-to   type=registry,ref=ghcr.io/OWNER/myapp:buildcache,mode=max ^
  --cache-from type=registry,ref=ghcr.io/OWNER/myapp:buildcache ^
  .
  • ref=...:buildcache みたいに 成果物とキャッシュを分けるのがコツ✨
  • registry backendの例はDocker公式にも載ってるよ (Docker Documentation)

さらに上級者向け（でも知っておくと強い）👇

  • compression=zstd など圧縮指定ができる（local/registryで対応） (Docker Documentation)

7) 実践③：GitHub Actionsなら type=gha が気持ちいい 🐙⚡️​

docker buildx build \
  -t ghcr.io/OWNER/myapp:latest \
  --push \
  --cache-to type=gha,mode=max \
  --cache-from type=gha \
  .
  • GHA backendは GitHub Actions内での推奨キャッシュとして案内されてるよ (Docker Documentation)
  • ただし繰り返し：RUN --mount=type=cache の中身は、そのままだとGHAに残らないケースがある（回避策あり） (Docker Documentation)

8) 落とし穴あるある 😵‍💫🪤（ここ超大事）​

🪤 ① 「--cache-to したのに速くならない」​

→ --cache-from を付け忘れてるパターンが最多です😂 外部キャッシュは 出す＆入れるが必須！ (Docker Documentation)

🪤 ② buildxのドライバ問題で詰む​

Dockerの デフォルト driver（docker driver） は、状況によって外部キャッシュが制限されます。 特に containerd image store が絡むところがポイント。Docker公式は👇こう明記してるよ：

  • デフォルトの docker driver は containerd image store を有効化している場合に限り、inline/local/registry/gha をサポート
  • それ以外のbackendは、別driverが必要 (Docker Documentation)

Docker Desktop（Windows） なら、設定で 「Use containerd for pulling and storing images」 をONにできるよ ✅ (Docker Documentation)

さらに注意：Docker Engine側でstorage backendを切り替えると、**古い方で作ったイメージ/コンテナが“見えなくなる”**ことがある（消えるわけじゃないけど焦るやつ）😱 (Docker Documentation)

🪤 ③ キャッシュが太ってディスクが溶ける 🫠💽​

local/registryは育つのが強みだけど、放置すると肥大化しがち。 → 定期的に掃除の設計（ディレクトリ消す/キャッシュref更新方針など）を入れると安心🧹

🪤 ④ 「GHAにしたのに依存DLが毎回走る」​

レイヤキャッシュは効いてるのに、キャッシュマウントが残ってないケースあり。 → 公式も「そのままだと保存されない」ことを説明して回避策（workaround）を紹介してるよ (Docker Documentation)

9) 🧪ミニ演習（15〜25分）＋測定📊✨​

演習A：localキャッシュで“2回目”を速くする​

  1. .buildx-cache を使って --cache-to/--cache-from を付けて2回ビルド
  2. 2回目が速くなることをログで確認（体感OK）👀✨ (Docker Documentation)

演習B：わざとキャッシュを壊して原因を当てる🕵️‍♂️​

  • Dockerfileで COPY . . の位置を早めてみる
  • 「どのステップから作り直しになった？」を説明してみる（第7章の復習にもなる）🧠

演習C：あなたの用途に“保存先”を選ぶ✍️​

  • ローカルだけ？CIあり？チーム共有？
  • local / registry / gha / inline のどれが合うか、1つに決めて理由を書く💡

10) 🤖AI活用（コピペでOK）プロンプト集 🧰✨​

✅ 相談テンプレ（保存先を決める）​

Docker BuildKit の外部キャッシュ保存先を選びたいです。
状況：
- 開発：Windows + Docker Desktop
- CI：GitHub Actions（あり/なし）
- レジストリ：GHCR（使える/使えない）
- チーム：個人/複数人
目的：ビルド時間短縮、安定、運用コスト最小

候補（inline/local/registry/gha）それぞれのメリット/デメリットと、
この状況での推奨を1つに絞って理由も教えて。

✅ 具体コマンド生成テンプレ​

このDockerfileとビルドコマンドを前提に、
- ローカル（type=local）
- CI（type=gha または type=registry）
の2パターンで、cache-to/cache-from を付けたコマンド例を作って。
前提として mode=max を使う版と、軽めの版（min）の違いも説明して。

まとめ：第16章のゴール 🏁🎉​

  • 外部キャッシュは “出す（--cache-to）”＋“入れる（--cache-from）” がセット ✅ (Docker Documentation)
  • 保存先は主に inline / local / registry / gha を押さえれば勝ち 🏆 (Docker Documentation)
  • WindowsのDocker Desktopは containerd image store が絡んで詰みやすいので、そこだけ要注意 😵‍💫 (Docker Documentation)

次の第17章は、この流れで buildxでキャッシュを“持ち運ぶ設計” をガッツリやっていくよ 🎒➡️🧰✨