DevOpsツールとベストプラクティスの習得 - DevOpsナレッジハブ DevOpsツールとベストプラクティスの習得 - DevOpsナレッジハブ

Dockerfileレイヤーキャッシュを極めてコンテナビルドを超高速化

Dockerfileレイヤーキャッシュを習得してDockerビルドを高速化し、開発ワークフローを効率化しましょう。この包括的なガイドでは、命令の順序最適化、マルチステージビルドの活用、キャッシュメカニズムの理解など、ビルド時間を大幅に短縮するベストプラクティスを紹介します。Dockerビルドを驚くほど高速にし、CI/CDの効率を向上させる方法を学びます。

Dockerfileレイヤーキャッシュを極めてコンテナビルドを超高速化

Dockerfileレイヤーキャッシュは、変更を考えている間にビルドが完了するか、すべてのコミットにコストがかかるかの違いを生みます。キャッシュは複雑ではありませんが、容赦がありません。間違ったファイルを早すぎるタイミングでコピーすると、Dockerは遅いステップを再実行せざるを得なくなります。

基本的な習慣はシンプルです。安定した作業を早い段階に、頻繁に変更される作業を遅い段階に配置し、ビルドコンテキストをクリーンに保つことです。これを理解すれば、ほとんどのDockerfileのパフォーマンス問題がビルド出力で見えるようになります。

Dockerレイヤーキャッシュの理解

Dockerはコンテナイメージをレイヤーで構築します。Dockerfileの各命令（RUN、COPY、ADDなど）は新しいレイヤーを作成します。イメージをビルドする際、Dockerは以前のビルドで同じコンテキスト（例：COPYの場合は同じファイル）でその特定の命令を実行したかどうかを確認します。キャッシュヒットが発生すると、Dockerは命令を再実行せずに既存のレイヤーをキャッシュから再利用します。これにより、特に計算コストの高い操作や大きなファイルのコピー時に、かなりの時間を節約できます。

主要な概念：

  • レイヤー： Dockerfile命令によって作成された不変のファイルシステムスナップショット。
  • キャッシュヒット： Dockerが特定の命令に対してキャッシュ内に同一のレイヤーを見つけた場合。
  • キャッシュミス： Dockerが一致するレイヤーを見つけられず、命令を実行しなければならず、後続のすべての命令のキャッシュが無効になる場合。

Dockerキャッシュの仕組み：メカニズム

Dockerは、命令自体と関連するファイルに基づいてキャッシュヒットを判断します。RUN echo 'hello'のような命令の場合、命令文字列が主要なキャッシュキーになります。COPYやADDのような命令の場合、Dockerは命令だけでなく、コピーされるファイルのチェックサムも計算します。命令またはファイルのチェックサムが変更されると、キャッシュミスが発生します。

つまり、Dockerfile命令または関連ファイルに変更があると、その命令と後続のすべての命令のキャッシュが無効になります。これは最適化の重要なポイントです。

キャッシュ利用を最大化するためのDockerfile最適化

Dockerのビルドキャッシュを活用する技術は、特に頻繁に変更される命令に対してキャッシュの無効化を最小限に抑えるようにDockerfileを構成することにあります。一般的な原則は、変更される可能性が低い命令をDockerfileの前半に、頻繁に変更される命令を後半に配置することです。

1. 命令を戦略的に順序付ける

黄金律： 安定した命令を最初に配置する。

典型的なWebアプリケーションのDockerfileを考えてみましょう。依存関係のインストール、アプリケーションコードのコピー、ビルドの実行またはサーバーの起動などの手順があるかもしれません。

非効率な例（キャッシュ無効化）：

FROM ubuntu:latest

# システムパッケージをインストール（変更は稀）
RUN apt-get update && apt-get install -y --no-install-recommends \
    python3 \
    python3-pip \
    && rm -rf /var/lib/apt/lists/*

# アプリケーションコードをコピー（非常に頻繁に変更）
COPY . .

# Python依存関係をインストール（頻繁に変更）
RUN pip install --no-cache-dir -r requirements.txt

# ... その他の命令

この例では、アプリケーションコードの1行を変更するたびに（COPY . .が実行されるため）、COPY . .と後続のすべての命令（RUN pip install ...）のキャッシュが無効になります。つまり、requirements.txtが変更されていなくてもpip installが再実行され、ビルド時間が長くなります。

最適化された例（キャッシュを最大化）：

FROM ubuntu:latest

# システムパッケージをインストール（変更は稀）
RUN apt-get update && apt-get install -y --no-install-recommends \
    python3 \
    python3-pip \
    && rm -rf /var/lib/apt/lists/*

# 最初に依存関係ファイルのみをコピー（変更は比較的少ない）
COPY requirements.txt .

# Python依存関係をインストール（requirements.txtが変更されていなければキャッシュ）
RUN pip install --no-cache-dir -r requirements.txt

# 残りのアプリケーションコードをコピー（非常に頻繁に変更）
COPY . .

# ... その他の命令

最初にrequirements.txtをコピーし、すぐにpip installを実行することで、Dockerは依存関係インストールレイヤーをキャッシュできます。アプリケーションコードのみが変更され（requirements.txtは同じまま）、pip installステップはキャッシュされ、ビルドが大幅に高速化されます。

2. マルチステージビルドを活用する

マルチステージビルドはイメージサイズを削減する強力な手法ですが、中間ビルド環境を分離することでビルド時間にも間接的に利益をもたらします。各ステージは独自のキャッシュレイヤーを持つことができます。

# ステージ1：ビルダー
FROM golang:1.20 AS builder
WORKDIR /app
COPY go.mod ./ 
COPY go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o myapp

# ステージ2：最終イメージ
FROM alpine:latest
WORKDIR /root/
COPY --from=builder /app/myapp .
CMD ["./myapp"]

このシナリオでは、アプリケーションのソースコードのみが変更された場合（go.modとgo.sumは変更されない）、ビルダーステージのgo mod downloadステップはキャッシュされます。ビルダーステージがコンパイルを再実行する必要がある場合でも、最終ステージはキャッシュされている可能性が高いalpine:latestイメージに基づいており、COPY --from=builder命令のみがアーティファクトmyappが変更された場合に再実行されます。

3. ADDとCOPYを賢く使う

  • COPY は通常、ローカルファイルをイメージにコピーするために推奨されます。シンプルで予測可能です。
  • ADD は、tarballの展開やリモートURLの取得など、より多くの機能を持っています。ただし、これらの追加機能は予期しない動作を引き起こしたり、キャッシュの無効化に異なる影響を与える可能性があります。ADDの高度な機能が明示的に必要でない限り、COPYを使用してください。

COPYを使用する場合は、粒度を細かくしてください。COPY . .の代わりに、上記の最適化された例のように、異なる速度で変更される特定のディレクトリやファイルをコピーすることを検討してください。

4. 同じRUN命令内でクリーンアップする

キャッシュの肥大化を防ぎ、イメージサイズを削減するために、作成されたのと同じRUN命令内でアーティファクト（パッケージマネージャーのキャッシュなど）を常にクリーンアップしてください。

悪い例：

RUN apt-get update && apt-get install -y some-package
RUN rm -rf /var/lib/apt/lists/*

ここでは、rmコマンドは別のRUN命令です。some-packageが更新された場合（最初のRUNでキャッシュミスが発生）、2番目のRUNは、新しいレイヤーにクリーンアップが厳密に必要でなくても実行されます。さらに重要なのは、最初のRUNによって作成された中間キャッシュレイヤーには、2番目のRUNでクリーンアップされる前にダウンロードされたパッケージリストが含まれている可能性があることです。

良い例：

RUN apt-get update && apt-get install -y some-package && rm -rf /var/lib/apt/lists/*

これにより、パッケージインストール中に作成された一時ファイルが即座に削除され、作成されるキャッシュレイヤーがよりクリーンなファイルシステム状態を表すことが保証されます。

5. 毎回依存関係をインストールしない

実証済みのように、依存関係定義ファイル（requirements.txt、package.json、Gemfileなど）をコピーし、アプリケーションのソースコードをコピーする前に依存関係をインストールすることは、基本的なキャッシュ最適化です。

6. キャッシュバスティング（必要な場合）

キャッシュを最大化することが目標ですが、キャッシュの再構築を強制したい場合もあります。これはキャッシュバスティングとして知られています。一般的な手法は次のとおりです。

  • コメントの変更： Dockerfileのコメント（#）は無視されるため、これは機能しません。
  • ダミー引数の追加： ARGを使用して変数を導入し、それを変更してキャッシュを破棄します。
    ARG CACHEBUST=1
RUN echo "Cache bust: ${CACHEBUST}" # CACHEBUSTが変更されるとこの命令は再実行されます
    その後、docker build --build-arg CACHEBUST=$(date +%s) . でビルドします。
  • 前のRUNコマンドの変更： Dockerfileの前半にあるコマンドを変更すると、後続のすべての命令のキャッシュが破棄されます。

キャッシュバスティングは控えめに使用し、通常は外部リソースの新しいダウンロードや、標準のキャッシュメカニズムで適切に処理されないもののクリーンビルドを確実にする必要がある場合にのみ使用してください。

Docker BuildKitと拡張キャッシュ

最近のDockerバージョンでは、BuildKitがデフォルトのビルダーエンジンとして導入されています。BuildKitはキャッシュに大幅な改善をもたらします。これには以下が含まれます。

  • リモートキャッシュ： 異なるマシンやCI/CDランナー間でビルドキャッシュを共有する機能。
  • より詳細なキャッシュ： 何が変更されたかのより良い識別。
  • 並列ビルド実行： キャッシュヒットがなくてもビルドを高速化。

BuildKitは通常デフォルトで有効になっており、多くの場合、すぐに優れたキャッシュを提供します。ただし、上記の原則を理解することで、BuildKit用にDockerfileを最適化することもできます。

効果的なDockerfileキャッシングのためのヒント

  • Dockerfileをクリーンで整理された状態に保つ： 可読性は最適化の機会を見つけるのに役立ちます。
  • キャッシュをテストする： 変更後、Dockerビルド出力を観察します。[internal]またはCACHEDタグを探してキャッシュヒットを確認します。
  • .dockerignoreを使用する： 不要なファイル（node_modules、.git、ビルドアーティファクトなど）がビルドコンテキストにコピーされるのを防ぎ、COPY命令を高速化し、意図しないキャッシュ無効化の可能性を減らします。
  • 定期的にDockerキャッシュをクリーンアップする： 時間が経つとキャッシュが大きくなる可能性があります。docker builder pruneを使用して未使用のビルドキャッシュレイヤーを削除します。

実際のNode.jsの例

キャッシュの問題はNode.jsプロジェクトで最もわかりやすいです。次のDockerfileは機能しますが、時間を無駄にします。

FROM node:22-slim
WORKDIR /app
COPY . .
RUN npm ci
RUN npm run build
CMD ["npm", "start"]

ソースが変更されるたびにCOPY . .が無効になり、npm ciが再実行されます。より良いバージョンは、依存関係メタデータをアプリケーションコードから分離します。

FROM node:22-slim
WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY . .
RUN npm run build

CMD ["npm", "start"]

これで、src/routes/account.tsの変更は依存関係インストールレイヤーを無効にしません。package-lock.jsonの変更は依然として無効にしますが、これはまさに望ましい動作です。

プロダクションイメージの場合は、これをマルチステージビルドと組み合わせます。

FROM node:22-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

FROM node:22-slim AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:22-slim AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
CMD ["node", "dist/server.js"]

これは長くなりますが、依存関係のダウンロード、アプリケーションビルド、ランタイムコンテンツの3つの関心事を分離します。CIランナーはコストのかかる部分をキャッシュでき、最終イメージはソースツリー全体や開発依存関係を必要としません。

.dockerignoreをキャッシュ戦略の一部として使用する

レイヤーキャッシュはDockerfile命令の順序だけの問題ではありません。ビルドコンテキストも重要です。.git、ローカルテスト出力、スクリーンショット、カバレッジレポート、node_modulesをビルドコンテキストに送信すると、Dockerがチェックサムを計算するファイルが増え、COPYが無効になる可能性が高まります。

アプリケーションの典型的な.dockerignoreは次のようになります。

.git
node_modules
dist
coverage
.env
*.log
tmp
.DS_Store

.envには注意してください。セキュリティと再現性のために、通常はイメージから除外する必要があります。ランタイム設定はコンテナ起動時に渡すべきであり、本当に機密性のないビルド時設定でない限り、ビルドに組み込むべきではありません。

キャッシュがあなたに嘘をついているときを知る

キャッシュはミスを隠すことがあります。よくある例は、外部リポジトリに依存するパッケージマネージャーコマンドです。次のように記述した場合：

RUN apt-get update
RUN apt-get install -y curl

キャッシュされたapt-get updateレイヤーは古くなる可能性があり、後のインストールステップは最新のパッケージメタデータを期待します。updateとinstallは一緒に保ってください。

RUN apt-get update \
  && apt-get install -y --no-install-recommends curl \
  && rm -rf /var/lib/apt/lists/*

同じ考え方が言語依存関係にも当てはまります。ロックファイルはビルドをより再現可能にし、キャッシュの動作を予測可能にするのに役立ちます。package-lock.json、pnpm-lock.yaml、poetry.lock、Gemfile.lock、go.sum、またはスタックに相当するものを使用してください。Dockerfileがネットワークから変動する依存関係バージョンをインストールする場合、キャッシュヒットは高速かもしれませんが、後で再ビルドが驚くべき結果になる可能性があります。

パッケージマネージャー向けのBuildKitキャッシュマウント

BuildKitは、パッケージマネージャーのキャッシュを最終イメージレイヤーに含めずに高速化するキャッシュマウントをサポートしています。例えば、npm：

# syntax=docker/dockerfile:1.7
FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
COPY . .
RUN npm run build

Pythonの場合：

# syntax=docker/dockerfile:1.7
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
  pip install --no-cache-dir -r requirements.txt
COPY . .

これが役立つかどうかは、CIのセットアップによります。リモートキャッシュのない短期間のランナーは、依然としてコールドスタートになります。ジョブ間でBuildKitキャッシュを保持するランナーは、多くの時間を節約できます。

CIでのリモートキャッシュ

ローカルキャッシュは簡単ですが、CIキャッシュには意図的なセットアップが必要です。docker buildxを使用すると、レジストリとの間でキャッシュメタデータをプッシュおよびプルできます。

docker buildx build \
  --cache-from=type=registry,ref=registry.example.com/myapp:buildcache \
  --cache-to=type=registry,ref=registry.example.com/myapp:buildcache,mode=max \
  -t registry.example.com/myapp:${GIT_SHA} \
  --push .

これにより、新しいランナーが以前のランナーによって構築されたレイヤーを再利用できるようになります。これは、依存関係のインストールや大規模なコンパイルステップに特に役立ちます。アクセス制御に注意してください。ビルドキャッシュには中間ステージからのファイルシステムスナップショットが含まれる可能性があるため、プライベートレジストリキャッシュはビルドインフラストラクチャの一部として扱い、公開スクラッチスペースとしては扱わないでください。

遅いDockerビルドのデバッグ

ビルドが予想外に遅い場合は、推測するのではなく出力を読みましょう。BuildKitは、どのステップがキャッシュされ、どのステップが実行されたかを表示します。依存関係インストールステップがキャッシュされていない場合は、前のCOPYまたはRUN行を確認してください。その前の何かが変更されています。

便利なチェック：

docker build --progress=plain .
docker buildx du
docker builder prune --filter until=24h

他のジョブがキャッシュに依存している共有ビルドホストでは、盲目的にプルーニングしないでください。プルーニングはディスク使用量が多い場合に役立ちますが、次のビルドを遅くする可能性があります。

実用的なレビューチェックリスト

Dockerfileをより高速なビルドのためにレビューする際は、上から下に進みながら次の質問を自問してください。

  • 安定したベースセットアップステップは、頻繁に変更されるソースファイルの前にありますか？
  • 依存関係マニフェストは、完全なアプリケーションの前にコピーされていますか？
  • .dockerignoreはローカルノイズやシークレットを除外していますか？
  • パッケージマネージャーのキャッシュは、同じレイヤーまたはBuildKitキャッシュマウントで処理されていますか？
  • 最終イメージには、実行に必要なものだけが含まれていますか？
  • CIは、ランナーが使い捨ての場合にリモートキャッシュを使用していますか？

高速なDockerビルドは、通常、多くの小さな退屈な選択の結果です。遅くて安定した作業を早い段階に、頻繁に変更される作業を遅い段階に配置します。ビルドコンテキストをクリーンに保ちます。そして、キャッシュが使用されていると想定するのではなく、ビルド出力で確認します。