cutover-planning

언제 사용하나요

• containerization-report.md 가 존재하고 이미지가 ECR 에 푸시되어 ECS/EKS 에 배포 가능한 상태일 때
• 기존(legacy) 환경의 production 트래픽을 신규(modernized) 환경으로 이전하는 마지막 단계
• DB 가 함께 이전되는 경우(DMS 기반 zero-downtime 마이그레이션) 데이터 동기화 전략 결정이 필요할 때
• 실패 시 자동 롤백 기준을 SLO 메트릭과 연결하여 사전 정의할 때

언제 사용하지 않나요

• 단순 Rehost(EC2 복제) 로 인프라 변경이 없는 경우 — 전용 컷오버 전략 불필요
• Stateless 내부 도구처럼 다운타임 허용이 명확한 경우 — 단순 배포 스크립트로 충분
• Repurchase(SaaS 전환) — SaaS 벤더 컷오버 지원 별도 활용

전제 조건

• .omao/plans/modernization/containerization-report.md 존재
• aidlc-construction/skills/risk-discovery 재실행 PASS (DB·세션·외부 연동 리스크 4축)
• ALB v2 또는 Route53 접근 권한, CloudWatch Alarms 생성 권한
• (DB 이전 시) DMS 복제 인스턴스 프로비저닝 가능 권한

절차

Step 1. 컷오버 전략 선택

전략	특징	적합 조건	롤백 시간
Canary	ALB weighted (1→10→50→100%)	Default 권장, 리스크 분산	즉시 (weight 조정)
Blue/Green	100% 즉시 전환	충분한 사전 테스트, 빠른 컷오버 필요	즉시 (DNS/listener)
Rolling	인스턴스 단위 교체	추가 자원 확보 어려울 때	느림 (인스턴스별 롤백)

선택 근거를 반드시 cutover-plan.md 에 기록합니다.

Step 2. Canary 단계 설계

권장 가중치 진행:

Step A: Blue 99% / Green 1%   — 30 min 관측
Step B: Blue 90% / Green 10%  — 1 hour 관측
Step C: Blue 50% / Green 50%  — 2 hour 관측
Step D: Blue 0%  / Green 100% — 24 hour 관측

ALB Weighted Target Group 전환 예시:

aws elbv2 modify-listener \
  --listener-arn ${LISTENER_ARN} \
  --default-actions '[{
    "Type":"forward",
    "ForwardConfig":{
      "TargetGroups":[
        {"TargetGroupArn":"'${BLUE_TG}'","Weight":90},
        {"TargetGroupArn":"'${GREEN_TG}'","Weight":10}
      ]
    }
  }]'

Step 3. Rollback Trigger 정의

다음 3축 중 하나라도 임계값 초과 시 자동 롤백 을 발동합니다.

메트릭	임계값 (Green TG)	관측 기간	액션
HTTP 5xx rate	> 1%	5 min	Revert to Blue 100%
P99 Latency	> 1.5× baseline	5 min	Revert to Blue 100%
SLO Error Budget	시간당 10% 소모	10 min	Pause + Executive 승인 요청
DB Replica lag	> 60s	1 min	Data sync 중단 + 수동 개입

CloudWatch Alarm → EventBridge → Lambda (가중치 되돌림) 파이프라인으로 자동화합니다.

Step 4. Data Synchronization (DMS)

기존 DB 가 Oracle/MySQL 등 다른 엔진이거나 region 이동이 있는 경우 DMS zero-downtime migration 을 사용합니다.

1. Full Load + CDC 모드 replication task 생성
2. Full Load 완료 후 CDC 가 Source WAL 을 계속 소비하도록 대기
3. 컷오버 직전 Source 쓰기 트래픽 차단 (read-only 모드)
4. DMS lag 0 확인
5. 애플리케이션 writer endpoint 를 Target 으로 전환
6. 검증 후 Source DB decommission

DMS CLI 예:

aws dms start-replication-task \
  --replication-task-arn ${TASK_ARN} \
  --start-replication-task-type start-replication

Step 5. Dual-Write 또는 Native Replication 대안

• Dual-Write: 애플리케이션 레벨에서 Source/Target 동시 기록. 데이터 정합성 위험 높음, 마이그레이션 동안 idempotency 핵심
• Native Replication: 동일 엔진(Oracle→Oracle, MySQL→MySQL) 에 한해 Binary log/logical replication 활용

Step 6. Pre-Cutover 검증 체크리스트

컷오버 개시 전 반드시 확인합니다.

• Green 환경 E2E 통합 테스트 PASS
• 보안 스캔(Trivy/grype) 0 HIGH/CRITICAL
• CloudWatch Alarms 4종 활성 (5xx/P99/SLO/DB lag)
• Runbook 작성 완료 (.omao/plans/modernization/cutover-runbook.md)
• Rollback 자동화 Lambda 배포 및 수동 트리거 테스트 완료
• 이해관계자 알림 채널 확정 (Slack #inc-modernization, PagerDuty)
• Maintenance window 공지 완료 (최소 72h 전)
• 고객 지원팀 FAQ 배포

Step 7. Post-Cutover 검증 체크리스트

Green 100% 도달 후 24h 이내 확인합니다.

• Error rate, latency, throughput 이 SLO 범위 내
• DB Replica lag == 0, 데이터 건수 일치 (hash 검증)
• 로그 수집 정상, X-Ray trace 누락 없음
• 비용 이상 징후 없음 (AWS Cost Anomaly Detection)
• 사용자 문의 스파이크 없음
• Blue 환경 shutdown 계획 승인 (보통 7-14일 유지 후 해체)
• audit.md 에 컷오버 타임라인 기록

Step 8. Output 산출

.omao/plans/modernization/cutover-plan.md 에 다음을 포함합니다.

# Cutover Plan
- strategy: Canary (1→10→50→100)
- sync_tool: DMS Full Load + CDC
- rollback_triggers: (Step 3 표)
- pre_cutover_checklist: (Step 6)
- post_cutover_checklist: (Step 7)
- maintenance_window: 2026-05-10 02:00 KST (2h)
- stakeholders: [CTO, SRE Lead, DBA, Support]
- runbook_link: cutover-runbook.md
- operations_handoff: agenticops plugin (operations-phase)

Step 9. Operations 핸드오프

audit-trail (agenticops) 을 호출하여 컷오버 종료 증거를 audit.md 에 고정합니다. 이후 운영은 agenticops 플러그인의 operations-phase 로 승계됩니다.

좋은 예시

• Canary 1→10→50→100 + CloudWatch Alarms 4종 + DMS CDC 0 lag → 무중단 컷오버
• Blue/Green 전환 + 7일 Blue 유지 + 자동 롤백 Lambda 2분 이내 동작
• 금융권 ISMS-P 대상 워크로드 + Maintenance window 72h 전 공지 + Executive 승인 체크포인트

나쁜 예시 (금지)

• Rollback trigger 임계값을 "경험에 따라" 로 기재 — 수치 없음
• DMS CDC lag 검증 없이 writer endpoint 전환 — 데이터 손실 위험
• Blue 환경 즉시 삭제 — 롤백 불가능
• Canary 100% 도달 후 Post-Cutover 체크리스트 생략
• Maintenance window 공지 없이 비즈니스 시간 중 컷오버

참고 자료

공식 문서

• AWS DMS Documentation — zero-downtime 마이그레이션
• ELB Weighted Target Groups — Canary 구현
• Route53 Weighted Routing — DNS 기반 전환
• CloudWatch Alarms — SLO 감시

원천 방법론 (MIT-0)

• traffic-cutover-strategy.md (Kiro) — 원본 컷오버 전략

관련 문서 (내부)

• ../containerization/SKILL.md — 선행 skill
• ../../CLAUDE.md — modernization 플러그인 개요
• /home/ubuntu/workspace/oh-my-aidlcops/plugins/agenticops/CLAUDE.md — Operations 핸드오프