AWS CodeDeploy로 무중단 배포 적용하며 겪은 삽질과 해결법

AWS CodeDeploy로 무중단 배포를 직접 적용해봤는데, 이게 생각보다 까다로워서 삽질을 꽤 했어요. 기존에 배포할 때 잠시 서비스가 끊겨서 사용자 불편을 준 적이 있었는데 무중단 배포는 꼭 해보고 싶었거든요.

이 글에서는 AWS CodeDeploy 기본 세팅부터 시작해서, 제가 막혔던 포인트와 해결 방법, 그리고 꼭 확인해야 하는 체크리스트까지 모두 담았어요. 따라 하시면서 막히는 부분 없이 무중단 배포까지 완성할 수 있을 겁니다.

개발 환경 / 버전 정보

이번 세팅에 사용한 AWS 리소스와 버전은 다음과 같아요.

• AWS CLI v2 - 배포 자동화 스크립트용
• AWS CodeDeploy - 배포 관리 및 무중단 배포 구현
• EC2 인스턴스 - 배포 대상 (Amazon Linux 2)
• appspec.yml - CodeDeploy 배포 설정 파일
• Node.js 18.x 애플리케이션 (예시 서버 앱)

AWS CodeDeploy 무중단 배포 핵심 세팅 방법

사실 이 부분이 가장 중요한데요, 무중단 배포를 하려면 Lifecycle Event Hooks와 Health Check Grace Period 설정이 필수거든요.

먼저 appspec.yml 기본 구조는 이렇게 생겼어요. 특히 BeforeInstall과 AfterInstall, ApplicationStart, ValidateService 스크립트 실행 순서가 정확해야 합니다.

version: 0.0
ios:
  - script: scripts/install_dependencies.sh
    runas: root
hooks:
  BeforeInstall:
    - location: scripts/stop_server.sh
      timeout: 300
      runas: root
  AfterInstall:
    - location: scripts/deploy.sh
      timeout: 300
      runas: root
  ApplicationStart:
    - location: scripts/start_server.sh
      timeout: 300
      runas: root
  ValidateService:
    - location: scripts/health_check.sh
      timeout: 60
      runas: root

각 스크립트는 서비스 중단 없이 교체하도록 조심해서 작성해야 하거든요. 예를 들어 stop_server.sh는 기존 프로세스를 안전하게 종료하고, start_server.sh는 새 버전을 띄우면서 문제가 없는지 바로 확인할 수 있게 하죠.

참고로 무중단 배포는 애플리케이션이 헬스체크를 통과해야 최종적으로 완료됩니다. 그래서 health_check.sh 스크립트가 아주 중요합니다.

중요 스크립트 예시 및 설명

아래는 제가 실제로 사용한 health_check.sh 예시입니다. 이 스크립트 없으면 배포가 실패해서 롤백되더라고요.

#!/bin/bash
# 무중단 배포를 위한 Health Check 스크립트

URL="http://localhost:3000/health"

response=$(curl --write-out %{http_code} --silent --output /dev/null $URL)

if [ "$response" -eq 200 ]; then
  echo "Health check passed."
  exit 0
else
  echo "Health check failed."
  exit 1
fi

이걸 통해 CodeDeploy가 서비스가 정상 실행 중인지 판단해 무중단 배포 성공 여부를 결정합니다.

여기서 많이들 막히는 것들

가장 막혔던 부분은 appspec.yml 구문 오류와 인스턴스 역할(IAM Role) 권한 문제였어요. 특히 권한이 부족하면 배포 중 EC2 인스턴스에 제대로 접근하지 못해서 계속 실패하더라고요.

이럴 때는 다음 IAM 정책이 EC2 역할에 제대로 붙어있는지 꼭 확인하세요.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "codedeploy:*",
        "s3:Get*",
        "s3:List*"
      ],
      "Resource": "*"
    }
  ]
}

그리고 보통 EC2 인스턴스에 CodeDeploy 에이전트가 설치되어 있어야 하는데, 이걸 누락해서 배포가 실패했던 경험도 있어요. 설치가 안 되어 있으면

sudo yum install -y aws-codedeploy-agent
sudo systemctl start codedeploy-agent
sudo systemctl enable codedeploy-agent

요렇게 설치하고 시작해야 합니다.

꼭 확인해야 할 AWS CodeDeploy 체크리스트 ✅

• EC2 인스턴스에 CodeDeploy 에이전트 정상 설치 및 실행 여부 - 에이전트 상태는 sudo systemctl status codedeploy-agent로 확인
• EC2 실행 역할(IAM Role)에 충분한 권한 부여 - codedeploy 및 S3 리소스 접근 권한 포함 여부 꼭 체크
• 앱셋(yml) 구문 및 스크립트 경로 정확성 - deploy 실패 원인 중 최다
• 스크립트 내 서비스 재시작 로직이 무중단 가능하게 작성되었는지 - 예: 새 프로세스 띄우고 기존 것 종료 순서
• Health Check가 올바르게 동작하는지 - 배포 완료 전 반드시 테스트

자주 물어보시는 것들

Q. 배포가 무조건 롤백되는데 왜 그런 걸까요?

A. 대부분 Health Check 실패나 스크립트 에러 때문입니다. 로그를 /var/log/aws/codedeploy-agent/codedeploy-agent.log에서 확인해서 어떤 상황인지 파악하세요.

Q. 무중단 배포 위해 꼭 해야 할 배포 전략이 있나요?

A. CodeDeploy에서 제공하는 Blue/Green 배포 전략을 권장합니다. 롤링 업데이트도 가능하지만, 무중단을 확실히 하려면 Blue/Green 설정이 더 안전해요.

마무리하며 스마트하게 무중단 배포 하기

무중단 배포는 단순히 설정 몇 줄 바꾸는 것보다, 서비스 상태 확인과 스크립트 안정성 확보가 더 중요하다는 걸 알게 됐어요. 이 글에서 알려드린 체크리스트와 스크립트 예시만 잘 따라가면 예전처럼 깜짝 서비스 중단 걱정은 안 하셔도 됩니다.

다음에는 이 배포와 연동해서 AWS CodePipeline 자동화까지 붙여서 CI/CD 파이프라인 구현 후기도 공유할게요!