3단계 CD 파이프라인 설계 - 100-hours-a-week/KTB4-3rd-wiki GitHub Wiki

3단계 CD(지속적 배포) 파이프라인 설계

CI에서 만들어진 동일한 Release Artifact를 Dev에서 검증한 뒤 Prod에 반영하는 절차와, 배포 성공 판정 및 실패 복구 방식을 정리한다. 이 문서는 V1의 단일 EC2와 Docker Compose 조건을 기준으로 한다. 세부 게이트와 실패 유형별 대응은 CD 파이프라인 설계 원문을 참고한다.

목차

1. 환경별 배포 목적

Dev는 기능 통합과 다중 사용자 테스트를 위한 공동 환경으로 사용한다. 로컬 환경마다 달라질 수 있는 API, 데이터베이스 스키마, 환경 변수와 WebSocket 연결 설정을 실제 통합 과정에서 확인하기 위해 기능 단위로 수시 배포한다. Prod는 실제 사용자와 데이터에 영향을 주므로 Dev 검증을 통과한 Release만 대상으로 계획 배포한다.

V1에서는 팀 규모와 예산에 비해 운영 대상을 늘리는 부담이 커 별도 Staging 환경을 추가하지 않는다. Dev가 통합·QA를 담당하고, Prod 배포 전에 운영 승인과 사전 점검을 둔다. 환경별 목적과 배포 빈도에 대한 상세 배경은 팀 운영 구조와 실행 제약 가정 및 CD 파이프라인 설계 원문에 정리되어 있다.

2. 배포 파이프라인

공통 CI에서 코드를 빌드하고 테스트한 뒤 Release Artifact를 만든다. Dev CD는 이를 자동 배포해 Health Check와 기능 검증을 수행하고, Prod CD는 Dev 검증 결과와 운영 승인을 확인한 뒤 동일한 Artifact를 계획 배포한다.

Pull Request → CI 검증 및 Artifact 생성
             → Dev 자동 배포 → Health Check·기능 검증·QA
             → Prod 승인 및 계획 배포
             → Health Check·Smoke Test·운영 지표 관찰
             → 성공 확정 또는 Rollback

Dev와 Prod에서 이미지를 각각 다시 만들지 않는다. Dev에서 확인한 것과 같은 이미지 Digest 및 Release를 Prod에 반영해야 배포 대상이 달라지는 일을 막고, 문제가 생겼을 때 이전 정상 버전을 명확히 선택할 수 있다. 배포 파이프라인의 상세 단계는 CD 파이프라인 설계 원문을 참고한다.

3. V1 배포 전략

단일 EC2와 Docker Compose 구성에서는 두 버전의 실행 단위를 동시에 유지하고 요청을 전환할 Load Balancer가 없다. 따라서 기존 컨테이너를 종료한 뒤 새 버전을 기동하는 Recreate 배포를 선택한다. 구현과 운영이 단순하고 추가 인프라가 필요하지 않은 대신, 교체 중 짧은 서비스 중단과 진행 중 요청 및 WebSocket 연결 종료가 발생할 수 있다.

이 영향을 줄이기 위해 Prod 배포는 피크 시간을 피해서 계획하고, 클라이언트 재접속 시 팟과 채팅 상태를 다시 조회할 수 있도록 한다. Rolling이나 Blue-Green 방식은 두 개 이상의 실행 인스턴스, 트래픽 전환 계층, 추가 리소스, 신·구 버전이 함께 동작하는 동안의 DB 호환성과 WebSocket 연결 Drain 정책을 필요로 하므로 V1 기본 전략에서는 제외한다. 방식별 비교와 Recreate 선택 근거는 원문 배포 전략에 설명되어 있다.

4. 배포 게이트와 성공 판정

배포 시작 전에는 CI 통과 여부와 대상 환경, Git SHA와 Release ID, 이미지 Digest를 확인한다. Dev 검증이 완료됐는지, 환경별 Secret과 설정이 준비됐는지, DB 변경이 구버전과 호환되는지, 백업과 롤백 대상이 있는지, 같은 환경에서 다른 배포가 진행 중이지 않은지도 확인한다. 필수 조건을 충족하지 못하면 배포를 시작하지 않는다.

컨테이너 프로세스가 실행됐다는 사실만으로 기동 성공을 선언하지 않는다. 애플리케이션 초기화와 필수 설정이 끝났는지 Startup Probe로 확인하고, 실제 요청을 받을 준비가 되었는지 Readiness Probe로 확인한다. Readiness는 준비되지 않은 컨테이너로 요청이 전달되는 것을 막지만, 대체 인스턴스나 전환 계층이 없는 단일 EC2에서 무중단 배포를 만들어 주지는 않는다.

Readiness 이후에는 로그인, 팟 조회·생성·참여, 좌석 초과 및 중복 참여 처리, 채팅 연결·메시지 송수신·재접속, 정산 조회 등 핵심 흐름을 Smoke Test로 확인한다. Health Check와 Readiness가 통과하더라도 핵심 사용자 흐름에 실패하면 배포를 성공으로 확정하지 않는다. Probe와 Smoke Test 기준은 배포 게이트와 성공 판정 기준에서 상세히 다룬다.

5. 실패 처리와 복구

CI 실패, 이미지 Push 실패, 기동·Probe 실패 또는 Smoke Test 실패가 발생하면 다음 단계로 진행하지 않는다. 앱 배포 후 오류율이 증가하거나 핵심 기능이 실패하면 직전 정상 이미지 Digest를 이용해 애플리케이션을 복구하고, 복구 후 지표와 Smoke Test를 다시 확인한다.

DB Migration 실패나 데이터 정합성 오류는 애플리케이션 이미지 롤백만으로 해결되지 않을 수 있다. 이 경우 DB 상태와 백업을 먼저 확인하고 쓰기 기능 보호, 데이터 대사·보정 또는 백업 복구를 별도로 판단한다. EC2나 디스크 장애는 컨테이너 재시작으로 해결된다고 가정하지 않고, 백업과 스냅샷을 이용해 새 환경을 복구한다. 유형별 대응은 원문 배포 실패 처리를 참고한다.

6. 현재 구조의 한계와 전환 조건

V1은 단일 EC2가 장애 지점이고, 자동 오케스트레이션 롤백이나 트래픽 전환 계층도 갖추지 않는다. 따라서 CD의 목표는 무중단 배포를 보장하는 데 있지 않고, Dev에서 빠르게 통합하고 Prod에는 검증된 동일 Artifact만 반영하며 실패 시 직전 정상 애플리케이션 버전으로 빠르게 복구하는 데 있다. 이 구조는 단일 호스트 장애나 클라우드 리전 장애까지 격리하지 못한다.

계획 배포 중 서비스 중단이 허용되지 않거나, 배포 중 팟 참여·채팅 실패가 반복되고, Prod 실행 인스턴스가 2개 이상으로 늘어 트래픽 전환 계층과 여유 리소스를 확보하면 Rolling 또는 Blue-Green 전환을 검토한다. 전환 전에 DB Migration의 하위 호환성과 WebSocket Drain·재접속 동작도 검증해야 한다.

홈