<aside> 🧭 권장 안전 기본값 반영 · Convention 2026-07-27.5. 확인된 코드·문서·Git 근거만 유지하고, 실제 장애·운영 성과·수치·조직 맥락은 근거가 없으면 제외했습니다. 실제 Notion UI의 목차 링크와 Full width 확인 전에는 진행 중 검수본으로 유지합니다.

</aside>

0. 결론: 한 번에 교체하지 않고, 되돌아갈 경로를 남긴 검증 단계였다

기존 단일 EC2·SSH 배포를 즉시 제거하지 않고, 전용 진입점과 ASG·CodeDeploy 경로를 별도로 구성해 검증하는 방향을 택했다. AppSpec에 설치·기동·검증 순서(lifecycle)를 명시하고, PM2 기동과 상태 확인 재시도(health retry)를 자동화해 재현 가능한 배포 경계를 만들었다.

다만 이 구조는 완성된 무중단·자동 확장 플랫폼이 아니다. 코드가 보존된 stage 기준으로 기존 SSH와 CodeDeploy가 같은 main push 뒤 병렬 실행되고, ASG 용량은 1대로 제한돼 있으며, fetched main에는 전환 파일이 없다. 따라서 이 회고는 “운영 완료”가 아니라 “병행 검증 경로와 전환 gate를 만든 과정”을 다룬다.

확인 축 구현된 범위 주장하지 않는 범위
배포 S3 artifact + CodeDeploy lifecycle main production 적용 완료
복구 ASG 교체 기반과 구 endpoint 유지 항상 즉시 version rollback
검증 PM2 preflight + bounded health retry zero downtime 보장
확장 ASG Min/Desired/Max 1 scale-out·고가용성
보안 env 제외 artifact OIDC·SSM 이전 완료
flowchart LR
  Push[stage의 main push 설계] --> Verify[공통 CI verify]
  Verify --> Legacy[기존 EC2 SSH 배포]
  Verify --> New[신규 S3·CodeDeploy 배포]
  Legacy --> OldEndpoint[기존 endpoint]
  New --> ASG[전용 ALB·ASG Max 1]
  ASG --> NewEndpoint[신규 endpoint]
  Client[frontend API endpoint] --> OldEndpoint
  Client -. 검증 후 전환 .-> NewEndpoint

1. 문서 목적 / 생성 배경

기존 구조는 한 대의 EC2에 SSH로 접속해 배포하고, 여러 서비스가 공용 ALB 규칙을 공유했다. 문서가 기록한 문제는 인스턴스 장애 시 수동 복구가 필요하고, 배포 과정과 서비스 진입점이 다른 시스템에 결합된다는 점이었다.

정석적으로는 한 번 만든 뒤 바꾸지 않는 배포 산출물(immutable artifact), 명시적인 단계별 실행 스크립트(lifecycle hook), 상태 확인 관문(health gate), 자동 복구, 비밀정보 관리와 관측 가능성을 갖춘 배포 그룹으로 옮기는 것이 자연스럽다. 하지만 저장소에는 기존 서버를 유지하면서 신규 경로를 검증한 흔적이 남아 있다. 실제 조직·일정 제약은 본인 검수 전까지 추정하지 않는다.

2. 처음 떠올린 방식과 찝찝했던 지점

가장 단순한 선택은 기존 SSH script를 계속 보강하는 것이다. 익숙하고 구성 요소가 적으며, 장애 시 직접 서버에 들어가 상태를 볼 수 있다.

하지만 서버가 교체될 수 있는 ASG에서는 인스턴스 안의 수동 변경을 신뢰할 수 없다. 어느 파일을 어디에 배치하고, 언제 의존성과 schema를 적용하고, 어떤 조건에서 트래픽을 허용할지가 코드로 남아야 한다. 그래서 배포를 “원격 명령 실행”이 아니라 “검증 가능한 lifecycle”로 바꾸는 쪽으로 판단이 이동했다.

3. 정석 구조 / 현실 제약 / 채택한 타협

flowchart TD
  Commit[검증된 commit] --> Artifact[immutable artifact]
  Artifact --> DeployGroup[deployment group]
  DeployGroup --> Candidate[new instance]
  Candidate --> Preflight[install/start/health]
  Preflight -->|pass| Shift[traffic shift]
  Preflight -->|fail| Rollback[automatic rollback]
  Secrets[OIDC + managed secrets] --> DeployGroup
  Metrics[logs/metrics/alarms] --> Rollback

이상적인 흐름은 동일 artifact를 후보 인스턴스에 설치하고, health와 alarm을 통과한 뒤 트래픽을 옮기며, 실패하면 자동 rollback하는 것이다. GitHub Actions는 OIDC 임시 자격증명을 쓰고 runtime secret은 SSM 또는 Secrets Manager에서 주입한다.

실제 검증 경로는 runner와 대상 EC2에서 build를 각각 수행하고, AMI 로컬 env와 static AWS secret을 사용했다. automatic rollback과 다중 인스턴스 운용도 저장소로 확인되지 않는다. 대신 기존 endpoint를 남겨 infrastructure path를 되돌릴 수 있게 하고 ASG Max를 1로 묶었다.

4. 선택지를 비교하면서 정리한 판단

선택지 장점 한계 판단
SSH 배포 유지 단순·익숙·즉시 진단 수동 복구·instance drift 기존 fallback으로 한시 유지
신규 경로 즉시 교체 중복 비용 제거 실패 시 복구 경로 축소 검증 전 제외
기존+ASG 병행 endpoint 단위 검증 이중 배포·환경 drift stage 구현
ASG Max 즉시 확대 가용성·확장성 cron/worker 중복·DB connection 분리 전 보류
AMI local env 기동이 단순 회전·stale·image secret 당시 구현, 이전 TODO
OIDC+managed secrets 장기 key 제거·회전 용이 IAM/주입 구성 필요 권장 후속

5. 수동 검증에서 CI gate가 있는 자동 경로로