2nd/10_Wiki/Topic_Programming/Coding/DevOps_Docker_Layer_Cache.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
devops-docker-layer-cache	Docker Layer Cache — 빌드 시간 90% 줄이기	Coding	draft	B	conceptual	2026-05-09	2026-05-09	devops docker build cache vibe-coding	language applicable_to Dockerfile / BuildKit Backend DevOps		multi-stage build COPY order BuildKit cache mount

Docker Layer Cache

Layer 1개 = 1줄 = 1 cache 단위. 변경 자주 안 되는 layer 위로, 자주 바뀌는 layer 아래로. 잘못 정렬하면 매 빌드마다 npm install. multi-stage + cache mount 가 표준.

📖 핵심 개념

• 각 RUN/COPY/ADD = 새 layer.
• 이전 layer 가 같으면 cache 재사용.
• 한 layer 가 바뀌면 그 아래 모두 invalidate.

💻 코드 패턴

잘못된 순서 — 매 빌드 npm install

FROM node:20-alpine
WORKDIR /app
COPY . .              # ❌ 소스 변경 시 invalidate
RUN npm install
RUN npm run build
CMD ["node", "dist/index.js"]

올바른 순서

FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci             # package*.json 안 바뀌면 cache hit

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

FROM node:20-alpine AS runtime
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=deps /app/node_modules ./node_modules
COPY package*.json ./
EXPOSE 3000
USER node
CMD ["node", "dist/index.js"]

BuildKit cache mount — 더 빠른 npm/apt cache

# syntax=docker/dockerfile:1.6
FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci

/root/.npm 가 build cache 에 보존 → 다른 빌드에서도 재사용.

Multi-stage 의 장점

• 최종 이미지 = runtime 만 (build tool 안 들어감).
• node_modules dev deps 안 들어감 (npm prune --production 또는 omit).
• 보안 surface 감소.

.dockerignore 필수

node_modules
.git
.env
.env.*
dist
*.log
coverage
__tests__

없으면 모든 파일이 build context 로 → COPY . 시 매번 invalidate.

Distroless / Alpine

FROM gcr.io/distroless/nodejs20-debian12 AS runtime
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
CMD ["dist/index.js"]

shell 없음 — 가장 작고 보안 강함. 단 디버깅 어려움.

Python 예시

FROM python:3.12-slim AS deps
WORKDIR /app
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install --user -r requirements.txt

FROM python:3.12-slim AS runtime
WORKDIR /app
COPY --from=deps /root/.local /root/.local
ENV PATH=/root/.local/bin:$PATH
COPY . .
CMD ["python", "main.py"]

🤔 의사결정 기준

의도	도구
빠른 dev rebuild	multi-stage + cache mount
작은 prod 이미지	distroless / alpine multi-stage
GPU / 큰 ML 모델	nvidia base image
멀티 아키텍처 (arm64 + amd64)	docker buildx
보안 스캔	trivy / snyk in CI

❌ 안티패턴

• Source 먼저 COPY: 매 commit 마다 deps 재설치.
• COPY . 가 .dockerignore 없이: 거대 build context.
• 모든 것 한 layer (RUN apt-get update && ...): 잘 쓰는 패턴이지만 layer 분리해야 cache 잘 작동. apt 는 보통 한 RUN.
• dev deps 가 prod 이미지에: 크기 + 보안. multi-stage.
• root 사용자로 CMD: 보안. USER node.
• layer 이미지 매번 :latest: pull 시점에 다른 버전. 명확한 태그.
• healthcheck 없음: orchestrator (k8s, ecs) 가 상태 모름.
• secret 을 image 에 baked: layer 에 영구 보관. build args + secrets mount (BuildKit).

🤖 LLM 활용 힌트

• multi-stage + .dockerignore + cache mount + non-root + healthcheck 5종.
• BuildKit syntax (# syntax=docker/dockerfile:1.6).

🔗 관련 문서

• DevOps_CI_CD_Pipeline_Patterns
• DevOps_Build_Performance