AWS CodeDeploy 무중단 배포 적용하며 겪은 실수와 해결 과정

AWS CodeDeploy를 통해 무중단 배포를 구현하려다가 예상보다 삽질을 많이 했어요. 특히 배포가 반려되거나 실패하면서 원인을 찾는 데 시간이 꽤 걸렸습니다. 그래서 직접 세팅하면서 겪은 실수와 에러, 그리고 그 해결법을 모두 정리해봤습니다.

이 글에서는 AWS CodeDeploy 기본 설정부터 무중단 배포에 필요한 AppSpec 파일 작성, 배포 그룹 구성, 그리고 제가 반복해서 실패했던 이유들을 구체적 명령어와 설정값 위주로 알려드릴게요. 만약 처음으로 CodeDeploy 무중단 배포를 적용하는 분이라면 이 글이 큰 도움이 될 겁니다.

개발 환경 / 버전 정보

제가 작업한 환경은 다음과 같습니다.

• AWS CLI : 2.12.0
• AWS CodeDeploy 에이전트 : 최신 (Linux EC2 인스턴스에 설치)
• EC2 인스턴스 OS : Amazon Linux 2
• 배포 애플리케이션 : Node.js Express 서버

AWS CodeDeploy 무중단 배포 적용한 후기 관련 정보

무중단 배포 핵심 설정, 이렇게 하면 됩니다

사실 무중단 배포라고 하면 복잡해 보이는데, AWS CodeDeploy에서 가장 중요한 건 AppSpec 파일과 배포 전략이에요. 저는 무중단 배포를 위해 blue/green 배포 방식을 선택했고, AppSpec YAML 설정을 이렇게 했습니다.

version: 0.0
os: linux
files:
  - source: /
    destination: /home/ec2-user/app
hooks:
  BeforeInstall:
    - location: scripts/stop_server.sh
      timeout: 60
      runas: ec2-user
  AfterInstall:
    - location: scripts/install_dependencies.sh
      timeout: 300
      runas: ec2-user
  ApplicationStart:
    - location: scripts/start_server.sh
      timeout: 60
      runas: ec2-user
  ValidateService:
    - location: scripts/validate.sh
      timeout: 30
      runas: ec2-user

이렇게 스크립트 훅으로 서버를 멈췄다가, 의존성 설치하고 다시 시작하는 순서로 설정했어요. 특히 ValidateService 훅을 넣어서 배포 후 서비스 정상 여부를 꼭 체크하게 했습니다.

그리고 배포 그룹을 만든 후, 배포 유형을 Blue/Green으로 설정했어요. 이렇게 하면 기존 인스턴스를 그대로 두고 새 인스턴스에 배포 후 트래픽 전환이 가능해 무중단 배포가 되거든요.

AWS CodeDeploy 무중단 배포 적용한 후기 관련 정보

여기서 삽질했던 부분들, 저는 이렇게 고쳤어요

사실 가장 오래 걸렸던 게 바로 이 부분입니다. 처음엔 배포가 매번 실패하거나 반려되어서 도대체 뭐가 문제인지 몰랐거든요.

가장 크게 문제 됐던 건 AppSpec 파일 문법 오류였어요. 제가 원래 JSON 형식으로 작성하다가 YAML로 변경했는데, 들여쓰기 하나 틀려서 배포가 완전 실패했습니다. 오류 메시지가 불분명해서 꽤 헤맸는데, Lambda 로그나 CodeDeploy 이벤트 로그에서 "Failure while parsing AppSpec" 메시지를 발견하고 문법 확인했어요.

Failed to parse AppSpec file: YAMLException: bad indentation of a mapping entry at line 12, column 5

이 부분에서 다시 AppSpec YAML을 좀 더 신경 써서 작성했더니 해결됐어요.

두 번째는 배포 그룹 구성 실수입니다. 저는 Blue/Green 배포를 설정하면서 대상 인스턴스 태그를 잘못 걸었었어요. 그래서 새 인스턴스에 트래픽이 안 넘어가서 무중단 배포 효과를 못 보고 계속 롤백됐습니다.

이걸 확인하려면 배포 그룹 설정 > 대상 인스턴스 > 태그 필터가 제대로 걸려있는지 꼭 봐야 합니다. CLI로 확인하는 명령어는 다음과 같아요.

aws deploy get-deployment-group --application-name MyApp --deployment-group-name MyDeploymentGroup

이 출력에서 ec2TagFilters 부분이 올바른지 꼭 확인했어요.

마지막으로 가장 당황스러웠던 건 배포 후 트래픽 전환 실패였습니다. 무중단 배포인데도 트래픽이 새 배포본으로 안 넘어가는 거예요. 그래서 로그를 살펴보니 로드밸런서 헬스체크 상태 이상으로 배포가 자동 롤백되고 있었습니다.

헬스체크 URL 경로나 포트, EC2 보안 그룹 설정이 맞는지 다시 점검하고, 헬스체크 상태가 정상(Healthy)일 때만 트래픽을 넘기도록 CodeDeploy 배포 그룹 설정을 조정했더니 문제가 해결됐어요.

AWS CodeDeploy 무중단 배포 적용한 후기 관련 정보

심화: 배포 스크립트 자동화 팁과 주의사항

여기서 좀 더 나아가면, 배포 스크립트를 최대한 idempotent(재실행해도 문제 없는)하게 만드는 게 중요해요. 예를 들어 scripts/install_dependencies.sh에서는 의존성 설치 전에 npm ci를 써서 정확히 잠금 파일 기준으로 설치하게 했고, scripts/start_server.sh에서는 이미 실행 중이면 다시 시작하지 않도록 체크하는 코드를 넣었어요.

# start_server.sh 예시
if pgrep node > /dev/null
then
  echo "Server is already running"
else
  nohup node /home/ec2-user/app/index.js > /home/ec2-user/app/out.log 2>&1 &
  echo "Server started"
fi

이렇게 하면 배포 중 서버가 중복 실행되거나 충돌 나는 걸 방지할 수 있더라고요.

자주 물어보시는 것들

Q. AWS CodeDeploy에서 배포가 " 스테이지 실패 "로 계속 뜰 때 어떻게 해야 하나요?

A. 보통 AppSpec 파일 문법 오류거나, 스크립트가 실행 중 에러가 났을 확률이 커요. aws deploy get-deployment 명령어로 실패 원인 로그를 확인하고, CodeDeploy 콘솔에서 구체적인 훅 실행 로그를 봐야 합니다. 스크립트에는 꼭 실행 권한(예: chmod +x scripts/*.sh)도 주셔야 해요.

Q. 무중단 배포인데도 서비스가 잠깐 멈춘 것 같아요. 왜 그런가요?

A. 보통 BeforeInstall 훅에서 서버를 중지시키고 ApplicationStart 훅에서 다시 시작하는 사이에 잠깐 서비스가 끊길 수 있어요. 완전 무중단을 원하면 Blue/Green 배포 시 트래픽 전환 타이밍을 신경 써야 하고, 혹은 Canary 배포 및 헬스체크 설정 튜닝도 필요합니다.

여기까지 제가 직접 겪으면서 배웠던 AWS CodeDeploy 무중단 배포 적용 경험담이었어요. 관련해 궁금한 점 있으면 언제든 코드나 설정 쪽에서 다시 점검해보시길 추천드립니다.

📌 함께 보면 좋은 글

• AWS S3 정적 웹사이트 호스팅과 CloudFront 연결하면서 겪은 문제와 해결법
• AWS VPC 서브넷 처음 구성할 때 헷갈렸던 개념과 비용 차이 비교
• AWS EC2 프리티어 서버 처음 만들기, 단계별로 제가 겪은 이야기