AWS CodeDeploy로 무중단 배포 직접 해봤더니 이런 점을 주의하세요

AWS CodeDeploy를 이용해 무중단 배포를 적용하다가 생각보다 복잡한 부분이 많아서 기록으로 남기게 됐어요. 실제로 저는 단계별로 차근차근 설정하면서 여러 번 삽질했는데, 그 과정과 팁을 모두 정리해봤습니다.

이 글에서는 AWS CodeDeploy 환경 세팅부터 배포 스크립트 작성, 무중단 배포를 위한 설정, 그리고 제가 겪은 문제와 해결 방법까지 전부 다뤄볼게요. 중간중간 꼭 필요한 명령어와 콘솔 화면 설정값도 구체적으로 넣었으니 도움이 될 거예요.

1. AWS CodeDeploy 시작 전 환경 및 준비물

사실 이 부분이 배포 성공에 가장 큰 영향을 미쳤어요. 저는 AWS EC2 인스턴스를 이미 운영 중이었고, GitHub에 애플리케이션 소스가 있었습니다. 먼저 CodeDeploy Agent가 EC2에 설치되어 있어야 해서 이걸 먼저 확인했죠.

아래 명령어로 설치 여부 확인부터 했어요:

sudo systemctl status codedeploy-agent

만약 설치가 안 돼 있으면, AWS 공식 문서에 나온 대로 아래처럼 설치했어요:

sudo yum update
sudo yum install -y ruby
cd /home/ec2-user
wget https://aws-codedeploy-ap-northeast-2.s3.ap-northeast-2.amazonaws.com/latest/install
chmod +x ./install
sudo ./install auto
sudo systemctl start codedeploy-agent
sudo systemctl enable codedeploy-agent

이게 제일 기본인데, 이 설치 단계에서 권한 문제로 실패하는 경우가 있어서 sudo 꼭 붙여서 실행했어요.

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

2. CodeDeploy 애플리케이션과 배포 그룹 생성 절차

이 단계를 건너뛰면 배포 자체가 안 되니 순서대로 했어요. AWS 콘솔에서 CodeDeploy 서비스로 들어가서 애플리케이션 생성 버튼 클릭 후 아래 순서대로 진행했습니다.

• 애플리케이션 이름 입력 (저는 my-app으로 정했어요)
• 배포 플랫폼은 EC2/온프레미스 선택
• 애플리케이션 생성 완료 후, 배포 그룹을 만들었죠.

배포 그룹 만들기에서는 다음 세팅을 했어요:

• 배포 그룹 이름 입력 (저는 my-app-deploy-group)
• 서비스 역할 선택 - CodeDeploy 역할이 반드시 있어야 합니다. IAM 콘솔에서 AWSCodeDeployRole 같은 역할을 만들어서 추가했어요.
• 배포 유형은 무중단 배포가 가능하게 In-place 배포 선택
• EC2 태그 기반 대상 선택 - EC2 인스턴스에 태그를 달아 배포 대상 지정. 저는 Key=Deploy, Value=True 태그를 달아 설정했어요.

이때 서비스 역할 권한이 충분한지 IAM에서 꼭 확인하세요. 권한 없으면 배포 실패하거든요.

3. 앱 배포용 appspec.yml 파일 작성하는 법

CodeDeploy가 무중단 배포 하려면 appspec.yml 파일이 프로젝트 루트에 꼭 있어야 해요. 저는 아래 예시처럼 작성했어요:

version: 0.0
os: linux
groups:
  - deploy_group
files:
  - source: /
    destination: /home/ec2-user/myapp
hooks:
  BeforeInstall:
    - location: scripts/stop_server.sh
      timeout: 300
      runas: ec2-user
  AfterInstall:
    - location: scripts/start_server.sh
      timeout: 300
      runas: ec2-user
  ApplicationStop:
    - location: scripts/stop_server.sh
      timeout: 300
      runas: ec2-user
  ApplicationStart:
    - location: scripts/start_server.sh
      timeout: 300
      runas: ec2-user
  ValidateService:
    - location: scripts/validate.sh
      timeout: 300
      runas: ec2-user

주목할 점은 hooks 부분인데, 무중단 배포를 위해 배포 전에 기존 서버 멈추고, 업데이트 후 다시 시작하는 스크립트를 연결하는 거예요. 저는 stop_server.sh 와 start_server.sh를 만들어서 서버 프로세스 관리하도록 했습니다.

stop_server.sh 예시

#!/bin/bash
# 기존 서버 프로세스 PID 찾아서 종료
PID=$(pgrep -f myapp)
if [ ! -z "$PID" ]; then
  echo "Stopping existing app process $PID"
  kill -15 $PID
  sleep 5
else
  echo "No existing app process found"
fi

start_server.sh 예시

#!/bin/bash
# 백그라운드로 앱 실행
nohup /home/ec2-user/myapp/start.sh > /home/ec2-user/myapp/app.log 2>&1 &
echo "App started"

이 스크립트들이 잘 동작해야 무중단 배포가 되는 거라서 꼭 권한 변경도 했어요:

chmod +x scripts/*.sh

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

4. 배포 실행 및 실제 무중단 배포 확인 방법

콘솔에서 배포를 시작하려면, CodeDeploy → 애플리케이션 → 배포 그룹에서 배포 생성 버튼을 눌렀어요. 그다음 배포할 S3 버킷이나 GitHub 소스 위치를 지정하면 됩니다.

제가 직접 한 명령어는 AWS CLI 활용한 배포 생성인데요, 이렇게 했어요:

aws deploy create-deployment \
  --application-name my-app \
  --deployment-group-name my-app-deploy-group \
  --s3-location bucket=mybucket,key=myapp.zip,bundleType=zip,eTag=1234567890abcdef \
  --description "Deploying new version"

이 명령어는 사전에 S3 버킷에 패키지를 올려놓은 상태여야 해요. 무중단 배포 성공 여부는 콘솔 화면에서 배포 상태가 Succeeded로 나와야 하고, 로그 탭에서 들어가면 hooks 스크립트 실행 결과도 볼 수 있어요.

5. 제가 막혔던 부분과 해결법 알려드려요

이 부분에서 많이들 헷갈리시는데, 저는 아래 3가지 문제를 겪었어요.

• CodeDeploy Agent가 설치됐지만 'Running' 상태가 아님: agent 로그에서 권한 오류가 있었는데, IAM 인스턴스 프로필에 CodeDeploy 권한을 넣어주니 해결됐어요.
• appspec.yml 문법 문제: 들여쓰기 하나 차이로 배포 중 'Invalid yaml' 오류가 났습니다. YAML은 공백과 들여쓰기에 엄격하니 반드시 스페이스 2칸으로 통일하세요.
• 배포 스크립트 내 서버 프로세스 종료가 안 됨: 프로세스 찾는 명령어가 틀렸다며 계속 서버가 종료 실패해서 무중단 배포가 깨졌는데 pgrep -f 'java -jar myapp.jar' 식으로 정확한 프로세스명을 써서 고쳤어요.

이 문제들은 배포 로그와 agent 로그에서 원인 파악했는데, 꼭 꼼꼼히 확인해보는 게 중요해요.

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

6. 이렇게 하면 조금 더 안정적인 무중단 배포 됩니다

저는 무중단 배포를 위해 아래 세 가지도 추가로 적용했어요.

• 배포 그룹에서 헬스 체크 옵션 설정 - ELB(로드밸런서) 연동 시 헬스 체크가 성공해야 다음 단계로 넘어가게 해서 무중단 보장
• BeforeInstall 훅 전에 validate.sh 스크립트를 만들어 서버 상태를 점검해 배포 실패 시 롤백하도록 구성
• 배포 로그를 CloudWatch와 연동해 실시간 모니터링 환경 구축

이렇게 하면 실제 운영 중 에러 있을 때 빠르게 감지하고 대처할 수 있어서 훨씬 안정적이에요.

7. 자주 물어보시는 것들

Q. 무중단 배포 시 점검 서버가 따로 필요한가요?

A. 기본적으로 CodeDeploy는 배포 대상 인스턴스에서 기존 프로세스를 중지하고 새로운 버전을 시작하는 방식이에요. 별도의 점검 서버는 필요 없지만, ELB와 헬스 체크를 함께 쓰는 게 안전합니다.

Q. 여러 인스턴스에 순차 배포 가능할까요?

A. 네, CodeDeploy 배포 그룹에서 배포 설정에 배치 크기(배포 단위 수)와 대기 시간을 조절해서 무중단으로 인스턴스를 순차적으로 업데이트할 수 있어요.

Q. 앱서버 외에 DB 변경은 어떻게 관리하나요?

A. CodeDeploy는 서버 배포에 집중된 도구라 DB 마이그레이션은 별도 CI/CD 파이프라인(예: Liquibase, Flyway)로 관리하는 게 일반적입니다. 배포 후 후크에서 DB 상태 체크만 하는 식으로 연동 가능해요.

제가 실제 AWS CodeDeploy 무중단 배포를 적용하면서 겪은 모든 절차를 최대한 자세하게 적었어요. 요즘 클라우드 인프라 자동화가 필수인 만큼, 이 경험이 여러분 배포 환경 구성에 큰 도움이 될 거라 믿습니다.

📌 함께 보면 좋은 글

• AWS CloudWatch 알람 설정하다가 여러 번 실수한 경험담과 해결법
• AWS EC2 프리티어 서버 처음 만들기, 제가 여러 번 실패한 경험담
• AWS SES로 이메일 발송 구현하며 겪은 비용과 설정 문제 해결기