Docker BuildKit & イメージレイヤー完全ガイド 2025: LLB、Cache Mount、Multi-Stage、OCI、ビルド最適化の徹底解説

$ docker build -t myapp .
Sending build context to Docker daemon  45.2MB
Step 1/12 : FROM node:14
Step 2/12 : WORKDIR /app
Step 3/12 : COPY package.json .
...

$ DOCKER_BUILDKIT=1 docker build -t myapp .
[+] Building 12.3s (15/15) FINISHED
 => [internal] load build definition       0.0s
 => [internal] load metadata                0.3s
 => [build 1/4] FROM node:14                0.0s (cached)
 => [build 2/4] COPY package.json .         0.1s
 => [build 3/4] RUN --mount=type=cache... npm install   8.2s
 ...

manifest.json          # イメージメタデータ
config.json            # コンテナ設定
layers/                # ファイルシステムレイヤー
├── blob1.tar.gz
├── blob2.tar.gz
└── blob3.tar.gz

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:abc123...",
    "size": 1234
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:def456...",
      "size": 54321
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:ghi789...",
      "size": 123456
    }
  ]
}

{
  "architecture": "amd64",
  "os": "linux",
  "config": {
    "Env": ["PATH=/usr/local/sbin:..."],
    "Cmd": ["node", "server.js"],
    "WorkingDir": "/app",
    "ExposedPorts": {
      "3000/tcp": {}
    }
  },
  "rootfs": {
    "type": "layers",
    "diff_ids": [
      "sha256:aaa...",
      "sha256:bbb..."
    ]
  },
  "history": [
    {
      "created": "2025-01-01T00:00:00Z",
      "created_by": "/bin/sh -c #(nop) ADD file:... in /"
    }
  ]
}

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:amd64...",
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:arm64...",
      "platform": {
        "architecture": "arm64",
        "os": "linux"
      }
    }
  ]
}

FROM alpine:3.19       # Layer 1: 基本 Alpine ファイルシステム
COPY app.js /app/      # Layer 2: /app/app.js を追加
RUN apk add nodejs     # Layer 3: nodejs パッケージと依存
RUN chmod +x /app/start.sh  # Layer 4: ファイル権限の変更

merged view:         /app/app.js, /usr/bin/node, ...
       ↑
   OverlayFS
  /   |   \
Layer 1 Layer 2 Layer 3 (read-only)
              \
           container writable layer (read-write)

Image A: ubuntu:22.04 + node + myapp
Image B: ubuntu:22.04 + node + other-app

Shared layers:
- ubuntu:22.04 (1 度だけ保存)
- node (1 度だけ保存)

Unique layers:
- myapp (A のみ)
- other-app (B のみ)

Dockerfile → Docker Daemon → Sequential steps

export DOCKER_BUILDKIT=1
docker build .

// ~/.docker/config.json
{
  "features": {
    "buildkit": true
  }
}

Dockerfile → Parser → LLB → Executor → Image

FROM node:18 AS base
RUN apt-get update && apt-get install -y python3

FROM base AS deps
COPY package.json .
RUN npm install

FROM base AS build
COPY . .
RUN npm run build

FROM nginx:alpine AS runtime
COPY --from=build /app/dist /usr/share/nginx/html

          node:18 (FROM)
                │
                ▼
         ┌─── base ───┐
         │            │
         ▼            ▼
       deps         build
         │            │
         ▼            ▼
   [unused]    nginx:alpine (FROM)
                     │
                     ▼
                  runtime

FROM alpine AS a
RUN sleep 10

FROM alpine AS b
RUN sleep 10

FROM alpine
COPY --from=a /tmp /a
COPY --from=b /tmp /b

import "github.com/moby/buildkit/client/llb"

st := llb.Image("alpine:3.19").
    Run(llb.Shlex("apk add --no-cache curl")).
    Root()

def, err := st.Marshal(ctx)
// BuildKit へ送信

# 悪い例
FROM golang:1.21
WORKDIR /app
COPY . .
RUN go build -o myapp

CMD ["./myapp"]

# Build stage
FROM golang:1.21 AS builder
WORKDIR /app
COPY . .
RUN go build -o myapp

# Runtime stage
FROM alpine:3.19
COPY --from=builder /app/myapp /myapp
CMD ["/myapp"]

FROM alpine AS tools
RUN apk add --no-cache curl jq

FROM scratch
COPY --from=tools /usr/bin/curl /usr/bin/curl
COPY --from=tools /usr/bin/jq /usr/bin/jq
# 必要なバイナリのみ

FROM scratch
COPY --from=python:3.11 /usr/local/bin/python3 /usr/local/bin/python3
# registry のイメージからもコピー可能

FROM rust:1.75 AS builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
COPY --from=builder /app/target/release/myapp /usr/local/bin/
CMD ["myapp"]

FROM node:20 AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

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

FROM node:20-slim
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=deps /app/node_modules ./node_modules
CMD ["node", "dist/server.js"]

FROM python:3.11 AS builder
COPY requirements.txt .
RUN pip install --target=/deps -r requirements.txt

FROM python:3.11-slim
COPY --from=builder /deps /usr/local/lib/python3.11/site-packages
COPY . /app
WORKDIR /app
CMD ["python", "main.py"]

FROM maven:3.9-eclipse-temurin-21 AS builder
WORKDIR /app
COPY pom.xml .
RUN mvn dependency:go-offline
COPY src ./src
RUN mvn package -DskipTests

FROM eclipse-temurin:21-jre
COPY --from=builder /app/target/*.jar /app.jar
CMD ["java", "-jar", "/app.jar"]

FROM alpine AS common
RUN apk add --no-cache ca-certificates

FROM common AS app1
# ...

FROM common AS app2
# ...

FROM node:20
COPY . .                    # 全体コピー
RUN npm install             # 毎回再実行

FROM node:20
COPY package*.json ./       # 依存ファイルのみ
RUN npm install             # 依存のインストール
COPY . .                    # 残り (キャッシュと無関係)

node_modules
.git
*.log
.env
dist
coverage

# syntax=docker/dockerfile:1.6

FROM node:20
WORKDIR /app
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm install
COPY . .
RUN npm run build

RUN --mount=type=cache,target=/root/.npm \
    npm ci

RUN --mount=type=cache,target=/root/.local/share/pnpm/store \
    pnpm install --frozen-lockfile

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

RUN --mount=type=cache,target=/root/.cache/go-build \
    --mount=type=cache,target=/go/pkg/mod \
    go build -o /app ./...

RUN --mount=type=cache,target=/usr/local/cargo/registry \
    --mount=type=cache,target=/app/target \
    cargo build --release

RUN --mount=type=cache,target=/root/.m2 \
    mvn package

docker buildx build \
  --cache-to type=registry,ref=myregistry.com/myapp:cache \
  --cache-from type=registry,ref=myregistry.com/myapp:cache \
  -t myapp:latest .

docker buildx build \
  --cache-to type=inline \
  --push \
  -t myregistry.com/myapp:latest .

# syntax=docker/dockerfile:1.6

FROM alpine
RUN --mount=type=bind,from=myorg/myrepo,target=/src \
    ...

# 悪い: トークンがイメージに残る
ARG GITHUB_TOKEN
RUN git clone https://$GITHUB_TOKEN@github.com/private/repo.git

# syntax=docker/dockerfile:1.6

FROM alpine
RUN --mount=type=secret,id=github_token \
    TOKEN=$(cat /run/secrets/github_token) && \
    git clone https://$TOKEN@github.com/private/repo.git

echo $GITHUB_TOKEN | docker buildx build \
  --secret id=github_token,src=/dev/stdin \
  -t myapp .

# syntax=docker/dockerfile:1.6

FROM alpine
RUN apk add --no-cache openssh-client git
RUN --mount=type=ssh \
    git clone git@github.com:private/repo.git

docker buildx build --ssh default -t myapp .

FROM ubuntu:22.04
RUN apt-get update && apt-get install -y curl

# 悪い: タグは移動可能
FROM node:20

# 良い: digest は不変
FROM node:20@sha256:8f0c5a7a1d0c7b8f...

docker pull node:20
docker images --digests | grep node

RUN apt-get update && apt-get install -y \
    curl=7.81.0-1ubuntu1.15 \
    && rm -rf /var/lib/apt/lists/*

requests==2.31.0
flask==3.0.0

{
  "dependencies": {
    "express": "4.18.2"
  }
}

ARG SOURCE_DATE_EPOCH=0
FROM golang:1.21
ENV SOURCE_DATE_EPOCH=$SOURCE_DATE_EPOCH
RUN go build -ldflags="-buildid=" -trimpath .

# 複数回ビルド
docker build -t myapp:1 .
docker build -t myapp:2 .

# イメージを比較
docker inspect myapp:1 | jq .RootFS.Layers
docker inspect myapp:2 | jq .RootFS.Layers

# 同一なら reproducible

FROM golang:1.21 AS builder
WORKDIR /app
COPY . .
RUN go build -o myapp

FROM gcr.io/distroless/base-debian12
COPY --from=builder /app/myapp /
CMD ["/myapp"]

FROM golang:1.21 AS builder
WORKDIR /app
COPY . .
RUN CGO_ENABLED=0 go build -o myapp

FROM scratch
COPY --from=builder /app/myapp /
CMD ["/myapp"]

trivy image myapp:latest

grype myapp:latest

syft myapp:latest -o spdx-json > sbom.json

# 署名
cosign sign --key cosign.key myregistry.com/myapp:latest

# 検証
cosign verify --key cosign.pub myregistry.com/myapp:latest

cosign sign myregistry.com/myapp:latest
# GitHub Actions OIDC による自動署名

RUN apt-get update
RUN apt-get install -y curl
RUN apt-get install -y jq
RUN rm -rf /var/lib/apt/lists/*

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

RUN apt-get update && \
    apt-get install -y build-essential && \
    make && \
    apt-get purge -y build-essential && \
    apt-get autoremove -y && \
    rm -rf /var/lib/apt/lists/*

# ビルドに不要
node_modules
.git
.github
*.log
*.md

# セキュリティリスク
.env
.env.local
**/secrets/

# 大容量の一時ファイル
dist
build
coverage
.next

# 悪い: 大きな base
FROM node:20              # 〜 1.1 GB

# 良い: slim
FROM node:20-slim         # 〜 240 MB

# さらに良い: alpine
FROM node:20-alpine       # 〜 180 MB

# 最高: distroless
FROM gcr.io/distroless/nodejs20-debian12  # 〜 180 MB、shell なし

FROM node:20-alpine

# 1. システム依存 (ほぼ変わらない)
RUN apk add --no-cache libc6-compat

# 2. パッケージマネージャ設定 (ほぼ変わらない)
WORKDIR /app
COPY package.json package-lock.json ./

# 3. 依存のインストール (package.json 変更時のみ)
RUN --mount=type=cache,target=/root/.npm \
    npm ci --only=production

# 4. アプリケーションコード (頻繁に変更)
COPY . .

# 5. ビルド (コード変更時のみ)
RUN npm run build

CMD ["node", "dist/server.js"]

docker buildx create --use
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myregistry.com/myapp:latest \
  --push .

- uses: docker/setup-buildx-action@v3

- uses: docker/build-push-action@v5
  with:
    context: .
    push: true
    tags: myregistry.com/myapp:${{ github.sha }}
    cache-from: type=gha
    cache-to: type=gha,mode=max
    platforms: linux/amd64,linux/arm64

FROM node:20
WORKDIR /app
COPY . .  # 1 行変わると全体無効化
RUN npm install

$ docker build .
Sending build context: 500 MB  # おかしい

ARG AWS_SECRET_KEY
ENV AWS_SECRET_KEY=$AWS_SECRET_KEY
# イメージに永遠に残る

FROM node:20 AS builder
# ... build stuff ...

FROM node:20-alpine
COPY --from=builder /app .  # alpine に glibc バイナリ
# 実行できない!

docker build -t myapp .
# arm64 でビルドされる
docker push myregistry.com/myapp
# サーバーで実行時に "exec format error"

FROM node:20
# デフォルトで root として実行
CMD ["node", "server.js"]

RUN useradd -u 1000 appuser
USER appuser

COPY . .  # すべてのファイル

COPY src ./src
COPY package.json tsconfig.json ./

docker buildx build --progress=plain .
# 全ログを出力

docker commit <intermediate_container_id> debug-image
docker run -it debug-image sh

RUN ...
# 失敗直前の状態をイメージに

docker build --target builder -t myapp:debug .
docker run -it myapp:debug sh

dive myapp:latest

docker history myapp:latest

skopeo inspect docker://nginx:latest

time docker build -t myapp .