README.md

섀도우 배포 (Shadow Deployment)

섀도우 배포는 실제 프로덕션 트래픽을 신버전에 미러링하여 사용자에게 영향 없이 신버전을 검증하는 방식이다. 구버전이 사용자 요청을 처리하고 응답을 반환하는 동안, 신버전은 동일한 요청의 복사본을 받아 처리하지만 그 응답은 무시된다.

개념

사용자 요청
     │
     ▼
[Traefik]
     │
     ├──────────────────────────────┐
     ▼                              ▼ (미러)
[app: 구버전]                 [shadow: 신버전]
사용자에게 응답 반환          응답 무시 (검증 전용)

언제 사용하나

• 신버전을 실 트래픽으로 검증하되 사용자에게 영향을 주고 싶지 않을 때
• 성능 비교: 동일한 요청에 대해 구버전과 신버전의 레이턴시/리소스 사용량을 비교할 때
• 새로운 알고리즘이나 DB 쿼리의 결과를 실 데이터로 검증할 때

주의사항

• 부작용(side effect)에 주의: 신버전이 DB 쓰기, 외부 API 호출 등을 수행하면 실제 데이터에 영향을 줄 수 있다. 읽기 전용 검증이거나 부작용 없는 엔드포인트에 적합하다.
• 신버전의 응답은 무시되므로 사용자 경험에는 영향이 없다.
• 미러링된 트래픽으로 인해 신버전 서버에 추가 부하가 발생한다.

구현 방식

Traefik v3의 Mirror 서비스를 사용해 트래픽을 미러링한다.

라우터 전환 단계

단계	적용 템플릿	설명
기본	templates/main.yaml	구버전만 트래픽 처리
섀도우 활성화	templates/shadow.yaml	구버전 처리 + 신버전에 미러링

배포 흐름

[구버전 기동] → [신버전 기동] → [shadow.yaml 적용: 미러링 시작] → [신버전 검증] → [완전 전환 또는 롤백]

파일 구조

plans/shadow/
├── main.yaml                  # 구버전(stable) docker compose 파일
├── shadow.yaml                # 신버전(shadow) docker compose 파일
├── docker-compose.yaml        # Traefik + 공통 네트워크 설정
├── dynamic/
│   └── routers.yaml           # Traefik이 감시하는 동적 라우터 설정
├── templates/
│   ├── main.yaml              # 구버전만 라우팅 (섀도우 비활성)
│   └── shadow.yaml            # 구버전 라우팅 + 신버전으로 미러링
└── scripts/
    ├── deploy-main.sh         # 구버전(stable) 컨테이너 기동
    ├── deploy-shadow.sh       # 신버전(shadow) 컨테이너 기동
    ├── apply-main.sh          # 구버전 전용 라우팅 복구
    ├── apply-percentage.sh    # 미러링 비율 설정 및 라우팅 적용
    └── deploy.sh              # 배포 메인 스크립트 (섀도우 배포 전체 흐름)