deployment-patterns

name	deployment-patterns
description	웹 애플리케이션을 위한 배포 워크플로우, CI/CD 파이프라인 패턴, Docker 컨테이너화, 헬스 체크(health checks), 롤백 전략 및 프로덕션 준비 체크리스트. 배포 인프라를 설정하거나 릴리스를 계획할 때 사용하세요.
metadata	{"origin":"ECC"}

배포 패턴 (Deployment Patterns)

프로덕션 배포 워크플로우 및 CI/CD 모범 사례입니다.

활성화 시기

• CI/CD 파이프라인 설정 시
• 애플리케이션을 Docker화할 때
• 배포 전략(Blue-Green, Canary, Rolling 등)을 계획할 때
• 헬스 체크 및 가용성 검사(Readiness probe) 구현 시
• 프로덕션 릴리스를 준비할 때
• 환경별 설정을 구성할 때

배포 전략

롤링 배포 (Rolling Deployment - 기본값)

인스턴스를 점진적으로 교체합니다. 롤아웃 중에 이전 버전과 새 버전이 동시에 실행됩니다.

인스턴스 1: v1 → v2  (첫 번째 업데이트)
인스턴스 2: v1        (여전히 v1 실행 중)
인스턴스 3: v1        (여전히 v1 실행 중)

인스턴스 1: v2
인스턴스 2: v1 → v2  (두 번째 업데이트)
인스턴스 3: v1

인스턴스 1: v2
인스턴스 2: v2
인스턴스 3: v1 → v2  (마지막 업데이트)

장점: 다운타임 없음, 점진적인 출시 단점: 두 버전이 동시에 실행되므로 하위 호환성(backward-compatible) 유지가 필요함 사용 시점: 일반적인 배포, 하위 호환이 가능한 변경 사항

블루-그린 배포 (Blue-Green Deployment)

동일한 환경을 두 개 운영합니다. 트래픽을 원자적으로(atomically) 전환합니다.

Blue  (v1) ← 트래픽 수신 중
Green (v2)   대기 중, 새 버전 실행 및 검증 중

# 검증 완료 후:
Blue  (v1)   대기 중 (필요 시 롤백용)
Green (v2) ← 트래픽 수신 중

장점: 즉각적인 롤백 가능 (Blue로 다시 전환), 깔끔한 전환 단점: 배포 중에 인프라 리소스가 2배로 필요함 사용 시점: 중요한 서비스, 문제 발생 시 무관용 원칙 적용이 필요한 경우

카나리 배포 (Canary Deployment)

트래픽의 적은 비율만 새 버전으로 먼저 보냅니다.

v1: 트래픽의 95%
v2: 트래픽의  5%  (카나리 테스트)

# 메트릭이 정상인 경우:
v1: 트래픽의 50%
v2: 트래픽의 50%

# 최종 완료:
v2: 트래픽의 100%

장점: 전체 출시 전 실제 트래픽으로 문제를 감지할 수 있음 단점: 트래픽 분할 인프라 및 모니터링 체계가 필요함 사용 시점: 트래픽이 많은 서비스, 위험 부담이 큰 변경, 기능 플래그 사용 시

Docker

멀티 스테이지 Dockerfile (Node.js)

# 스테이지 1: 의존성 설치
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --production=false

# 스테이지 2: 빌드
FROM node:22-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build
RUN npm prune --production

# 스테이지 3: 프로덕션 이미지
FROM node:22-alpine AS runner
WORKDIR /app

RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001
USER appuser

COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
COPY --from=builder --chown=appuser:appgroup /app/package.json ./

ENV NODE_ENV=production
EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

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

멀티 스테이지 Dockerfile (Go)

FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /server ./cmd/server

FROM alpine:3.19 AS runner
RUN apk --no-cache add ca-certificates
RUN adduser -D -u 1001 appuser
USER appuser

COPY --from=builder /server /server

EXPOSE 8080
HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:8080/health || exit 1
CMD ["/server"]

멀티 스테이지 Dockerfile (Python/Django)

FROM python:3.12-slim AS builder
WORKDIR /app
RUN pip install --no-cache-dir uv
COPY requirements.txt .
RUN uv pip install --system --no-cache -r requirements.txt

FROM python:3.12-slim AS runner
WORKDIR /app

RUN useradd -r -u 1001 appuser
USER appuser

COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
COPY --from=builder /usr/local/bin /usr/local/bin
COPY . .

ENV PYTHONUNBUFFERED=1
EXPOSE 8000

HEALTHCHECK --interval=30s --timeout=3s CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health/')" || exit 1
CMD ["gunicorn", "config.wsgi:application", "--bind", "0.0.0.0:8000", "--workers", "4"]

Docker 모범 사례

# 권장(GOOD) 사례
- 특정 버전 태그 사용 (node:latest 대신 node:22-alpine 사용)
- 이미지 크기 최소화를 위해 멀티 스테이지 빌드 활용
- non-root 사용자로 실행
- 레이어 캐싱을 위해 의존성 파일을 먼저 복사
- node_modules, .git, 테스트 파일 제외를 위해 .dockerignore 사용
- HEALTHCHECK 명령 추가
- docker-compose 또는 k8s에서 리소스 제한(limits) 설정

# 기피(BAD) 사례
- root 사용자로 실행
- :latest 태그 사용
- 전체 저장소를 하나의 COPY 레이어로 복사
- 프로덕션 이미지에 개발 의존성(dev dependencies) 설치
- 이미지에 비밀 정보 저장 (환경 변수 또는 비밀 관리 도구 사용)

CI/CD 파이프라인

GitHub Actions (표준 파이프라인)

name: CI/CD

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test -- --coverage
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: coverage
          path: coverage/

  build:
    needs: 
     
       
    
        
        
        
        
           
             
             
        
        
           
               
           
           

  
     
     
       
     
    
          
         

파이프라인 단계

PR 생성 시:
  lint → typecheck → 단위 테스트 → 통합 테스트 → 프리뷰 배포

main 브랜치 병합 시:
  lint → typecheck → 단위 테스트 → 통합 테스트 → 이미지 빌드 → 스테이징 배포 → 스모크 테스트 → 프로덕션 배포

헬스 체크 (Health Checks)

헬스 체크 엔드포인트

// 단순 헬스 체크
app.get("/health", (req, res) => {
  res.status(200).json({ status: "ok" });
});

// 상세 헬스 체크 (내부 모니터링용)
app.get("/health/detailed", async (req, res) => {
  const checks = {
    database: await checkDatabase(),
    redis: await checkRedis(),
    externalApi: await checkExternalApi(),
  };

  const allHealthy = Object.values(checks).every(c => c.status === "ok");

  res.status(allHealthy ? 200 : 503).json({
    status: allHealthy ? "ok" : "degraded",
    timestamp: new Date().toISOString(),
    version: process.env.APP_VERSION || "unknown",
    uptime: process.uptime(),
    checks,
  });
});

async function (): <> {
   {
     db.();
     { : , :  };
  }  (err) {
     { : , :  };
  }
}

Kubernetes Probes

livenessProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 10
  periodSeconds: 30
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 5
  periodSeconds: 10
  failureThreshold: 2

startupProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 0
  periodSeconds: 5
  failureThreshold: 30    # 30 * 5초 = 최대 150초 스타트업 대기

환경 구성 (Environment Configuration)

Twelve-Factor App 패턴

# 모든 구성은 환경 변수를 통해 관리 -- 코드에 포함 금지
DATABASE_URL=postgres://user:pass@host:5432/db
REDIS_URL=redis://host:6379/0
API_KEY=${API_KEY}           # 비밀 정보 관리 도구에서 주입
LOG_LEVEL=info
PORT=3000

# 환경별 동작 제어
NODE_ENV=production          # 또는 staging, development
APP_ENV=production           # 명시적인 앱 환경 플래그

구성 검증 (Configuration Validation)

import { z } from "zod";

const envSchema = z.object({
  NODE_ENV: z.enum(["development", "staging", "production"]),
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
});

// 실행 시 검증 - 설정이 잘못된 경우 즉시 실패(Fail-fast) 처리
export const env = envSchema.parse(process.env);

롤백(Rollback) 전략

즉각적인 롤백

# Docker/Kubernetes: 이전 이미지로 전환
kubectl rollout undo deployment/app

# Vercel: 이전 배포본으로 전환
vercel rollback

# Railway: 이전 커밋으로 재배포
railway up --commit <previous-sha>

# 데이터베이스: 마이그레이션 롤백 (복구가 가능한 경우)
npx prisma migrate resolve --rolled-back <migration-name>

롤백 체크리스트

• 이전 이미지/아티팩트가 사용 가능하고 태그가 지정되어 있음
• 데이터베이스 마이그레이션이 하위 호환 가능함 (파괴적인 변경 없음)
• 피처 플래그(Feature flags)를 통해 배포 없이 새 기능을 비활성화할 수 있음
• 에러율 급증에 대한 모니터링 알람이 구성되어 있음
• 프로덕션 릴리스 전 스테이징에서 롤백 테스트 완료

프로덕션 준비 체크리스트 (Production Readiness Checklist)

배포 전 반드시 확인하세요:

애플리케이션

• 모든 테스트 통과 (단위, 통합, E2E)
• 코드나 설정 파일에 하드코딩된 비밀 정보 없음
• 모든 엣지 케이스를 포괄하는 에러 처리
• 구조화된 로깅(JSON) 적용 및 개인 정보(PII) 포함 금지
• 의미 있는 상태를 반환하는 헬스 체크 엔드포인트

인프라

• Docker 이미지가 재현 가능하게 빌드됨 (버전 고정)
• 환경 변수가 문서화되고 실행 시 검증됨
• 리소스 제한(CPU, 메모리) 설정
• 수평적 확장(Horizontal scaling) 구성 (최소/최대 인스턴스)
• 모든 엔드포인트에 SSL/TLS 적용

모니터링

• 애플리케이션 메트릭 수집 (요청율, 지연 시간, 에러 등)
• 에러율 임계값 초과 시 알람 구성
• 로그 수집 및 검색 엔진 설정
• 헬스 엔드포인트에 대한 업타임 모니터링

보안

• 의존성 패키지에 대한 보안 취약점(CVE) 스캔 완료
• 허용된 오리진에 대해서만 CORS 구성
• 공개 엔드포인트에 전송률 제한(Rate limiting) 적용
• 인증 및 인가 체계 검증 완료
• 보안 헤더 설정 (CSP, HSTS, X-Frame-Options)

운영

• 롤백 계획이 문서화되고 테스트됨
• 프로덕션 규모의 데이터에 대해 데이터베이스 마이그레이션 테스트 완료
• 일반적인 장애 시나리오에 대한 매뉴얼(Runbook) 준비
• 당번(On-call) 순번 및 에스컬레이션 경로 정의

이 스킬을 사용하는 시점

• CI/CD 파이프라인 설정 시
• 애플리케이션 Docker화 시
• 배포 전략 계획 시
• 헬스 체크 구현 시
• 프로덕션 릴리스 준비 시
• 배포 관련 문제 해결 시