[G1-Sync] Manual knowledge update

2026-05-09 21:08:02 +09:00
parent f0befc887a
commit 93ec7e9056
363 changed files with 68333 additions and 64 deletions
@@ -0,0 +1,141 @@
+---
+id: devops-docker-layer-cache
+title: Docker Layer Cache — 빌드 시간 90% 줄이기
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [devops, docker, build, cache, vibe-coding]
+tech_stack: { language: "Dockerfile / BuildKit", applicable_to: ["Backend", "DevOps"] }
+applied_in: []
+aliases: [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
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY . .              # ❌ 소스 변경 시 invalidate
+RUN npm install
+RUN npm run build
+CMD ["node", "dist/index.js"]
+```
+
+### 올바른 순서
+```dockerfile
+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
+```dockerfile
+# 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
+```dockerfile
+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 예시
+```dockerfile
+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]]