docker-buildx

Docker Buildx — ビルドエンジンとマルチプラットフォーム

docker build、buildx、マルチプラットフォームビルド、ビルドの最適化に関する専門的なガイダンスです。

使用する場面

ユーザーが次の内容に言及した場合は、必ずこのスキルを使用してください：

• 「docker build」、「buildx」、「イメージのビルド」
• 「マルチプラットフォーム」、「マルチアーキテクチャ」、「マルチプラットフォームビルド」
• 「linux/arm64」、「linux/amd64」
• 「BuildKit」、「Build Cloud」
• 「ビルドの高速化」、「ビルドキャッシュ」
• 「Docker build が遅い」、「docker build を高速化する方法」
• 複数の CPU アーキテクチャ向けにイメージをビルドする必要がある場合

基本コマンド

# Basic build
docker build -t myapp:v1 .

# Build with BuildKit (default in modern Docker)
DOCKER_BUILDKIT=1 docker build -t myapp:v1 .

# Build from specific Dockerfile
docker build -f Dockerfile.prod -t myapp:v1 .

# No cache rebuild
docker build --no-cache -t myapp:v1 .

Buildx — マルチプラットフォームビルダー

セットアップ

# Create a builder instance
docker buildx create --name multiarch --use

# Inspect available platforms
docker buildx inspect --bootstrap

複数のプラットフォーム向けにビルドする

# Build and push directly (single command)
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myorg/myapp:v1.0.0 \
  --push .

# Build and load to local Docker (single platform only)
docker buildx build \
  --platform linux/arm64 \
  -t myapp:arm64 \
  --load .

# Build and export as tar
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myapp:v1.0.0 \
  --output type=tar,dest=myapp.tar .

プラットフォームのエイリアス

エイリアス	アーキテクチャ
linux/amd64	Intel/AMD 64 ビット
linux/arm64	ARM 64 ビット（Apple Silicon、AWS Graviton）
linux/arm/v7	ARM 32 ビット（Raspberry Pi 3）
linux/arm/v6	ARM 32 ビット（Raspberry Pi Zero）

BuildKit の機能

シークレットのマウント

# Dockerfile
RUN --mount=type=secret,id=npmrc \
  cp /run/secrets/npmrc .npmrc && \
  npm ci && \
  rm .npmrc

docker buildx build --secret id=npmrc,src=$HOME/.npmrc -t myapp .

キャッシュのマウント（ビルド間で保持）

# Python: persist pip cache
RUN --mount=type=cache,target=/root/.cache/pip \
  pip install -r requirements.txt

# Node.js: persist npm cache
RUN --mount=type=cache,target=/root/.npm \
  npm ci

# Go: persist module cache
RUN --mount=type=cache,target=/root/.cache/go-build \
  go build -o server .

SSH フォワーディング

# Clone private repo during build
RUN --mount=type=ssh \
  git clone [email protected]:org/private-repo.git

docker buildx build --ssh default -t myapp .

インラインキャッシュ（イメージにキャッシュをエクスポート）

# Export cache metadata into the image itself
docker buildx build \
  --build-arg BUILDKIT_INLINE_CACHE=1 \
  -t myapp:latest \
  --push .

# Later builds can use this image as cache source
docker build --cache-from myapp:latest -t myapp:v2 .

レイヤーキャッシュ — ビルド前にプルする

# Pull previous image for layer cache
docker pull myapp:latest || true
docker build \
  --cache-from myapp:latest \
  -t myapp:${TAG} .

GitHub Actions — マルチプラットフォーム

- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
  with:
    platforms: linux/amd64,linux/arm64
    push: true
    tags: user/app:latest
    cache-from: type=gha          # GitHub Actions cache
    cache-to: type=gha,mode=max

ワークフロー — 推奨ビルド手順

ステップ 1: ビルダーを作成する: docker buildx create --name multiarch --driver docker-container --use ステップ 2: 方式を選択する: 単一プラットフォーム（--load）にするか、マルチプラットフォーム（--push）にするか？クロスコンパイルにするか、QEMU にするか？ ステップ 3: Dockerfile を設定する: --platform=$BUILDPLATFORM と ARG TARGETOS TARGETARCH を使用します ステップ 4: ビルドを実行する: docker buildx build --platform linux/amd64,linux/arm64 -t app --push . ステップ 5: 確認する: docker buildx imagetools inspect app でマルチアーキテクチャの manifest を確認します

注意点 — よくある落とし穴

• マルチプラットフォームでの --load: --load が機能するのは単一プラットフォームのみです。→ 対処方法: マルチプラットフォームの場合は --push または --output type=oci,dest=image.tar を使用します。または、単一プラットフォームを --load でビルドします。
• QEMU エミュレーションは低速です: AMD 上で ARM をビルドすると、5～10 倍遅くなります。→ 対処方法: CI ではネイティブ ARM ランナー（GitHub Actions の ubuntu-24.04-arm）を使用します。または、ネイティブなマルチアーキテクチャビルダーを提供する Docker Build Cloud を使用します。
• BuildKit はデフォルトで有効です: 最新の Docker では、BuildKit がデフォルトで使用されます。→ 対処方法: Docker 23 以降では DOCKER_BUILDKIT=1 を指定しても何も変わりません。BuildKit を明示的に制御するには docker buildx build を使用します。
• 先にプルせずに --cache-from を使用する: Docker はキャッシュイメージを自動的にプルしません。→ 対処方法: docker build --cache-from myapp:latest の前に docker pull myapp:latest || true を実行します。

境界 — 対応範囲（適用できる場面とできない場面）

分類	場面	説明
✅ 対応	マルチプラットフォームビルド（linux/amd64,arm64）	buildx + QEMU／クロスコンパイル／ネイティブノード
✅ 対応	BuildKit の高度な機能	シークレットのマウント、キャッシュのマウント、SSH フォワーディング、インラインキャッシュ
✅ 対応	Docker Build Cloud の利用	クラウドビルド + チームで共有するキャッシュ
⚠️ 条件付き	マルチプラットフォーム + --load	単一プラットフォームのみ対応。マルチプラットフォームでは --push が必要です
⚠️ 条件付き	ローカルに ARM と QEMU がない場合	docker run --privileged --rm tonistiigi/binfmt --install all が必要です
❌ 対象外	Dockerfile の作成	docker-dockerfile を使用します
❌ 対象外	基本的な docker build/tag/push	docker-build を使用します
❌ 対象外	コンテナオーケストレーション（Compose/Swarm）	docker-compose/docker-production を使用します

このスキルを使用しない場面

❌ 使用しない	✅ 代わりに使用
Dockerfile の内容を記述する	docker-dockerfile
Compose ベースのビルド	docker-compose
Docker の基本操作	docker-basics
コンテナの実行	docker-run

セキュリティと安定性

• ビルドログにシークレットを絶対に露出させないでください。BuildKit の --secret または CI のシークレットマスキングを使用します。
• マルチプラットフォームイメージはレジストリにプッシュする必要があります。--load が機能するのは単一プラットフォームのみです。
• CI のキャッシュイメージは || true を付けてプルしてください。初回のビルドではキャッシュが存在しません。

📚 公式ドキュメントの参考資料

ドキュメント	URL
Docker Build	https://docs.docker.com/build/
Buildx リファレンス	https://docs.docker.com/reference/cli/docker/buildx/
BuildKit	https://docs.docker.com/build/buildkit/
Docker Build Cloud	https://docs.docker.com/build-cloud/
マルチプラットフォームビルド	https://docs.docker.com/build/building/multi-platform/
ビルドキャッシュ	https://docs.docker.com/build/cache/

🧭 Docker スキルの旅

📍 現在地：docker-buildx — ビルドエンジン

← 前へ：docker-dockerfile — Dockerfile の作成 → 次へ：docker-run — コンテナの実行 / docker-cicd — CI/CD