GitHub Actions + Docker + NGINX를 활용한 Blue/Green 무중단 배포 환경 구축

들어가며

이번 프로젝트를 진행하는 과정에서, 배포 작업 중 서버 다운 문제를 경험하게 되었습니다. 이전까지는 새로운 버전의 애플리케이션을 배포할 때마다 불가피하게 트래픽 중단이나 에러 발생이 동반되었습니다. 특히, 서비스가 실시간으로 운영되는 상황에서 사용자가 접속중일 때 배포가 이루어지면, 잠시 동안 서비스 이용에 불편을 겪거나, 일부 요청이 처리되지 않는 경우가 발생하기도 했습니다.

 

이러한 문제를 해결하기 위해, 배포 과정에서 발생할 수 있는 다운타임을 최소화할 수 있는 방법을 고민하게 되었습니다. 여러 배포 전략을 살펴본 결과, 무중단 배포 방식을 적용하는 것이 효과적이라 판단하였고, 이를 구현하기 위해 GitHub Actions와 Blue-Green 배포 방식을 도입하게 되었습니다.

 

CI/CD 도구 선정 이유

배포 자동화를 구현하는데 있어, Jenkins와 GitHub Actions 두가지 옵션을 비교하였습니다.

 

Jenkins는 다양한 언어와 소스코드 리포지토리에 대해 지속적인 통합(CI)과 배포(CD)를 지원하며, 자유도가 높고 커스터마이징이 용이한 장점이 있습니다. 하지만, Jenkins를 사용하기 위해서는 별도의 서버를 구축하고 관리해야 하고, 초기 설정이 다소 무겁다는 단점이 있습니다.

 

반면, GitHub Actions는 GitHub에서 공식적으로 제공하는 워크플로우 자동화 도구로, 별도의 인프라를 구성할 필요없이 코드 푸시, PR, Release 등 GitHub내의 이벤트에 반응하여 자동으로 빌드 및 배포 작업을 실행할 수 있습니다.

 

이번 프로젝트는 규모가 크지 않고, 복잡한 커스터마이징이 필요하지 않은 상황이었기 때문에, 보다 간단하고 설정이 빠른 GitHub Actions를 선택하게 되었습니다.

 

배포 전략 선정 이유

가장 중요한 과제 중 하나는 서비스 중단 없이 새로운 버전을 안정적으로 배포하는 방법이었습니다. 이를 위해 다양한 무중단 배포 전략을 검토하였고, 실제 프로젝트 상황에 가장 적합한 방식을 선택하고자 다음과 같은 방법들을 고려하였습니다.

 

Rolling 배포

Rolling 배포 방식은 기존 서버를 순차적으로 교체하는 방식으로 리소스 사용량이 적고 간단하게 구현할 수 있는 장점이 있습니다. 그러나 배포 중 구버전과 신버전이 동시에 서비스되는 구간이 존재하기 때문에, 이로 인한 호환성 문제나 예기치 못한 오류 발생 가능성을 완전히 배제할 수 없다는 점이 리스크로 작용했습니다.

 

Canary 배포

Canary 배포 방식은 일부 서버나 사용자에게만 새 버전을 먼저 배포하고 문제가 없을 경우 전체로 확장하는 전략으로, 배포 리스크를 최소화할 수 있습니다. 하지만 초기에는 트래픽 분기 로직이나 조건 처리에 대한 추가적인 구현 복잡도가 존재했고, 프로젝트 규모와 인프라 구성 상 이를 적용하기에는 다소 과하다는 판단을 내렸습니다.

 

Blue-Green 배포

Blue-Green 배포 방식은 기존 서비스(Blue)와 새로운 버전(Green)을 동시에 구동시킨 뒤, 기능 검증을 마치고 로드 밸런서를 통해 트래픽을 Green으로 일괄 전환하는 방식입니다. 문제가 발생하더라도 다시 Blue로 빠르게 전환이 가능해 안전성과 복구 가능성이 가장 높은 방식이라고 판단했습니다.

 

무엇보다 Blue-Green 배포 전략 자체가 간단하고 명확하여, 기존의 자동화 파이프라인과 통합하기 쉬운 방법이라 판단해 해당 방식을 최종적으로 선택하게 되었습니다.

 

EC2 서버 파일 구조

/wegotoo                       # 프로젝트 루트 디렉토리
│
├── /nginx                     # Nginx 관련 설정 디렉토리
│   ├── /conf                  # Nginx 설정 파일 디렉토리
│   │   └── wegotoo.conf       # Nginx 서버 설정 파일
│   │
│   └── docker-compose.yml     # Nginx 및 기타 서비스 컨테이너 설정 파일
│
└── deploy.sh                  # 배포 자동화 스크립트

 

NGINX

NGINX를 사용한 이유는 트래픽 전환을 안전하고 빠르게 하기 위해 사용했습니다.

 

Blue-Green 배포의 핵심은 현재 운영중인 인스턴스와 새 인스턴스를 동시에 띄워놓고, 트래픽만 전환하는 것입니다. 이때 트래픽을 어떻게 전환할 것인가가 핵심인데, 그 역할을 NGINX의 리버스 프록시로 수행합니다.

docker-compose.yml

services: 
    nginx:
        image: nginx:latest
        container_name: nginx
        ports:
            - 80:80
        volumes:
            - ./conf:/etc/nginx/conf.d

이 설정 파일은 로컬 디렉토리 ./conf에 있는 파일들을 NGINX 컨테이너 내부의 /etc/nginx/conf.d 경로에 마운트하도록 구성한 것입니다. 즉, NGINX가 실제로 사용하는 설정 파일을 호스트 시스템에서 관리하고 수정할 수 있는 구조를 만들어 줍니다.

 

wegotoo.conf

server {
    listen 80;
    listen [::]:80;
    server_name api.wegotoo.net;

    location / {
        proxy_pass http://172.17.0.1:8081;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_buffer_size 128k;
        proxy_buffers 4 256k;
        proxy_busy_buffers_size 256k;
    }
}

이 설정 파일은 api.wegotoo.net으로 들어오는 모든 요청을 Docker 호스트의 특정 포트로 전달하는 역할을 합니다. NGINX 컨테이너는 이 설정 파일을 읽어, 요청을 어디로 전달할지(리버스 프록시 대상)를 결정하게 됩니다.

 

deploy.sh

이 코드는 Docker와 NGINX를 활용한 Blue-Green 배포 자동화 스크립트입니다. 기존 컨테이너와 새 컨테이너를 번갈아가며 사용하며, 무중단으로 애플리케이션을 업데이트할 수 있도록 합니다.

# 애플리케이션 이름 및 포트 설정
APP_NAME="wegotoo"
BLUE_PORT=8081
GREEN_PORT=8082

# 컨테이너 이름 설정
BLUE_CONTAINER="wegotoo_blue"
GREEN_CONTAINER="wegotoo_green"

# 헬스 체크를 위한 URL 기본 주소
HEALTH_CHECK_URL="http://localhost"

echo "1️⃣ 현재 실행중인 컨테이너 확인 중..."
# 현재 실행 중인 컨테이너가 BLUE인지 확인
if docker ps --format '{{.Names}}' | grep -q "$BLUE_CONTAINER"; then
    ACTIVE=$BLUE_CONTAINER
    ACTIVE_PORT=$BLUE_PORT

    IDLE=$GREEN_CONTAINER
    IDLE_PORT=$GREEN_PORT
else 
    ACTIVE=$GREEN_CONTAINER
    ACTIVE_PORT=$GREEN_PORT

    IDLE=$BLUE_CONTAINER
    IDLE_PORT=$BLUE_PORT
fi

echo "2️⃣ $IDLE 컨테이너에 최신 이미지로 배포 시작..."
# 이미지 이름 설정
IMAGE="$APP_NAME/prod:latest"

# 기존 IDLE 컨테이너가 실행중이면 종료
docker rm -f $IDLE || true
# 새 컨테이너 실행
docker run -d --name $IDLE -p $IDLE_PORT:8080 $IMAGE

echo "3️⃣ 헬스 체크 시작..."
# 새 컨테이너가 정상 작동하는지 확인
for i in {1..10}; do
    sleep 5
    STATUS=$(curl -s "$HEALTH_CHECK_URL:$IDLE_PORT/health-check" | jq -r '.status')
    if [ "$STATUS" == "OK" ]; then
        echo "✅ 헬스 체크 성공!"
        break
    fi
    if [ $i -eq 10 ]; then
        echo "❌ 헬스 체크 실패! 롤백합니다."
        docker rm -f $IDLE || true
        exit 1
    fi
done

echo "4️⃣ NGINX 설정 파일 포트 스위칭 중..."
NGINX_CONTAINER_NAME="nginx"
# NGINX 설정 파일에서 포트를 ACTIVE → IDLE로 변경
docker exec $NGINX_CONTAINER_NAME sed -i "s/$ACTIVE_PORT/$IDLE_PORT/g" /etc/nginx/conf.d/wegotoo.conf
# NGINX 재시작 (리로드)
docker exec $NGINX_CONTAINER_NAME nginx -s reload

echo "5️⃣ 이전 ACTIVE 컨테이너 종료..."
# 이전 ACTIVE 컨테이너 종료
docker rm -f $ACTIVE || true

echo "✅ 배포 완료! 현재 서비스 포트는 $IDLE_PORT 입니다."

1. 현재 실행중인 컨테이너 파악
   • 현재 실행중인 컨테이너가 BLUE인지 GREEN인지 파악합니다.
   • 그에 따라 ACTIVE(현재 서비스 중), IDLE(대기 중)를 설정합니다.
2. IDLE 컨테이너에 최신 이미지로 배포 시작
   • 이전 IDLE 컨테이너가 실행중일 수도 있는 상황이 있기 때문에 제거하고 최신 이미지를 사용해 새 컨테이너를 실행합니다.
3. 헬스 체크
   • 지정한 헬스 체크 엔드 포인트를 통해 컨테이너가 정상적으로 동작하는지 최대 10회 확인합니다.
   • 성공 시 루프를 빠져 나오고, 실패 시 배포를 중단합니다.
4. NGINX 설정 스위칭
   • 현재 서비스 중인 포트를 새 컨테이너의 포트로 변경합니다.
   • 이 설정은 NGINX 내부의 wegotoo.conf 파일을 수정하는 방식입니다.
   • 이후 NGINX를 reload하여 설정을 반영합니다.
5. 이전 컨테이너 정리
   • 이전 컨테이너(ACTIVE)를 종료 및 삭제하여 리소스를 정리합니다.

 

GitHub Actions

GitHub Actions workflows 흐름

1. 코드가 main 브랜치에 push 되면, GitHub Actions가 트리거 됩니다.
2. Gradle을 통해 애플리케이션을 빌드하고, Docker 이미지를 Docker Hub에 push 합니다.
3. EC2 서버로 SSH 접속 후, deploy.sh 스크립트를 실행하여 Blue-Green 배포를 수행합니다.
4. 배포가 완료되면 NGINX 설정을 변경하여 트래픽을 새로운 컨테이너로 전환합니다.

wegotoo_prod.yml

name: wegotoo_prod  

on:  
  push:  
    branches: [ "main" ]  
  pull_request:  
    branches: [ "main" ]  

jobs:  
  develop:  
    # 실행 환경  
    runs-on: ubuntu-22.04  
    steps:  
      - name: Checkout  
        uses: actions/checkout@v3  

      # JDK 17  
      - name: Set up JDK 17  
        uses: actions/setup-java@v3  
        with:  
          java-version: '17'  
          distribution: 'temurin'  

      # Gradle Caching  
      - name: Gradle Caching  
        uses: actions/cache@v3  
        with:  
          path: |  
            ~/.gradle/caches  
            ~/.gradle/wrapper  
          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}  
          restore-keys: |  
            ${{ runner.os }}-gradle-  

      # application-prod.yml  
      - name: Copy prod Secret  
        env:  
          DEV_SECRET: ${{ secrets.APPLICATION_PROD_YML }}  
          DEV_SECRET_DIR: src/main/resources  
          DEV_SECRET_DIR_FILE_NAME: application-prod.yml  
        run: echo $DEV_SECRET | base64 --decode >> $DEV_SECRET_DIR/$DEV_SECRET_DIR_FILE_NAME  

      # application-jwt.yml  
      - name: Copy jwt Secret  
        env:  
          DEV_SECRET: ${{ secrets.APPLICATION_JWT_YML }}  
          DEV_SECRET_DIR: src/main/resources  
          DEV_SECRET_DIR_FILE_NAME: application-jwt.yml  
        run: echo $DEV_SECRET | base64 --decode >> $DEV_SECRET_DIR/$DEV_SECRET_DIR_FILE_NAME  

      # application-oauth.yml  
      - name: Copy oauth Secret  
        env:  
          DEV_SECRET: ${{ secrets.APPLICATION_OAUTH_YML }}  
          DEV_SECRET_DIR: src/main/resources  
          DEV_SECRET_DIR_FILE_NAME: application-oauth.yml  
        run: echo $DEV_SECRET | base64 --decode >> $DEV_SECRET_DIR/$DEV_SECRET_DIR_FILE_NAME  

      # ./gradlew 권한 설정  
      - name: ./gradlew 권한 설정  
        run: chmod +x ./gradlew  

      # Gradle Build  
      - name: Build with Gradle  
        run: |  
          ./gradlew clean  
          ./gradlew compileJava  
          ./gradlew build  

      # Docker Build하고 DockerHub에 Push      - name: Docker Build & Push to DockerHub  
        run: |  
          docker login -u ${{ secrets.DOCKER_USERNAME }} -p ${{ secrets.DOCKER_PASSWORD }}  
          docker build -t ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKER_PROD_REPO }}:latest .  
          docker push ${{ secrets.DOCKER_USERNAME }}/${{ secrets.DOCKER_PROD_REPO }}:latest  

      # GitHub IP를 요청  
      - name: Get GitHub IP  
        id: ip  
        uses: haythem/public-ip@v1.2  

      # AWS 세팅  
      - name: AWS Setting  
        uses: aws-actions/configure-aws-credentials@v1  
        with:  
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY }}  
          aws-secret-access-key: ${{ secrets.AWS_SECRET_KEY }}  
          aws-region: ap-northeast-2  

      # GitHub IP를 AWS에 추가  
      - name: Add GitHub IP to AWS  
        run: |  
          aws ec2 authorize-security-group-ingress --group-id ${{ secrets.AWS_SG_ID }} --protocol tcp --port 22 --cidr ${{ steps.ip.outputs.ipv4 }}/32  

      # SSH Key로 서버에 접속하고 deploy.sh 실행
      - name: Run deploy.sh on EC2
        uses: appleboy/ssh-action@v0.1.6  
        with:  
          host: ${{ secrets.EC2_PROD_HOST }}  
          username: ${{ secrets.EC2_USERNAME }}  
          key: ${{ secrets.KEY }}  
          port: 22  
          script: |  
            cd wegotoo  
            chmod +x deploy.sh
            ./deploy.sh

      # Security Group에서 Github IP를 삭제  
      - name: Remove Github IP From Security Group  
        run: |  
          aws ec2 revoke-security-group-ingress --group-id ${{ secrets.AWS_SG_ID }} --protocol tcp --port 22 --cidr ${{ steps.ip.outputs.ipv4 }}/32

 

결과

실행 전

컨테이너 상태

사용중인 포트: 8081 / 컨테이너 이름: wegotoo_blue

NGINX 설정 파일

:8081로 트래픽 전달

GitHub Actions를 통해 위 스크립트를 실행하기 전에는 wegotoo_blue 컨테이너가 :8081번 포트에서 서비스 중이고, NGINX 설정 파일 역시 proxy_pass http://172.17.0.1:8081;로 지정되어 있습니다. 

 

실행 후

컨테이너 상태

사용중인 포트: 8082 / 컨테이너 이름: wegotoo_green

NGINX 설정 파일

:8082로 변경됨

실행된 후에는 새롭게 기동된 wegotoo_green 컨테이너가 :8082번 포트에서 정상적으로 구동된 이후, NGINX 설정이 자동으로 proxy_pass http://172.17.0.1:8082;로 전환되었습니다. 그 결과 트래픽이 기존의 wegotoo_blue 컨테이너가 아닌 wegotoo_green 컨테이너로 문제 없이 이동함을 확인할 수 있었습니다.