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 (한 번만 저장)
- node (한 번만 저장)

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
# 이미지 레지스트리의 이미지에서도 가능

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 . .  # 한 줄 바뀌면 전체 무효화
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 .