GitHub Actions(CI/CD), AWS S3, CodeDeploy 지속적 통합, 배포 자동화

이전 포스팅에서 AWS EC2, RDS`MySQL`, ElastiCache`Redis`를 활용하여 배포 인프라를 형성하고 cli환경에서 직접 배포작업까지 완료하였습니다.

[AWS] EC2, RDS, ElastiCache 인스턴스 생성부터 배포까지

애플리케이션의 안정성과 확장성을 확보하기 위해 클라우드 서비스를 활용하고 있습니다. AWS`Amazon Web Services`는 그중에서도 가장 널리 사용되는 클라우드 플랫폼으로, 강력하고 유연한 인프라

tao-tech.tistory.com

이번 포스팅에서는 AWS 인프라 형성한 것을 기반으로 AWS S3, CodeDeploy, GitHub Actions`CI/CD`를 활용하여 `지속적 통합`, `배포 자동화`의 개념과 구현까지 알아보도록 하겠습니다.

개발 환경
운영체제 : macOS
스프링 버전 : Spring Boot 3.3.3
빌드 툴 : Gradle
언어 : Java `openJDK 21`
데이터베이스 : MySQL, Redis, H2(테스트용)
데이터베이스 환경 관리 : Docker Compose

동작 흐름

이번 포스팅에서 구현하고자 하는 동작흐름은 다음과 같습니다.

main push
- GitHub Actions 워크플로우가 트리거 됩니다.
[CI] BuildAndTest.yml 실행
- 코드 빌드 및 테스트 진행
- `CI 실패` 워크플로우가 중단되며 이는 곧 파이프라인의 종료를 의미합니다.
- `CI 통과` 다음 CD 단계로 진행됩니다.
[CD] BuildAndDeploy.yml 실행
- 배포 준비 작업을 수행하며 zip 파일 생성 `jar 파일`, `appspec.yml`, `deploy.sh`가 포함됩니다.
[AWS] S3 zip 파일 업로드
- 생성된 zip 파일을 AWS S3 버킷에 업로드합니다.
[AWS] CodeDeploy 동작
- `CodeDeploy`는 배포를 트리거하고, 배포 그룹에 지정된 `EC2 인스턴스`에 배포를 시작합니다.
배포 그룹에 설정된 EC2 인스턴스에 배포 시작
- `CodeDeploy`는 EC2 인스턴스 내에서 `CodeDeploy Agent`가 작업을 실행하도록 명령합니다.
CodeDeploy Agent 동작
- EC2 내부에서 배포 작업을 시작합니다.
S3에서 zip 파일 다운로드
- `CodeDeploy Agent`가 `S3`에서 zip 파일을 다운로드하고 `appspec.yml`에 정의된 경로로 파일을 복사합니다.
기존 Application 중단 및 배포된 jar 실행
- `deploy.sh`를 통해 애플리케이션을 재시작합니다. `기존 프로세스 중단` → `새 jar 파일 실행`
배포 성공, 실패 응답
- `CodeDeploy Agent`가 `AWS CodeDeploy`에게 배포 결과를 응답하며, 이는 `AWS CodeDeploy` 대시보드에 기록됩니다.

1. 초기 설정

GitHub Actions를 통한 자동화 배포 전 배포 인프라를 형성합니다.

배포 인프라(AWS EC2, RDS, ElastiCache) 형성은 이전 포스팅에서 확인할 수 있습니다.

[AWS] EC2, RDS, ElastiCache 인스턴스 생성부터 배포까지

tao-tech.tistory.com

1-1. CodeDeploy Agent 설치

`EC2 서버`에 배포작업을 수행 할 `CodeDeploy Agent`를 설치합니다.

// 시스템 패키지 목록 업데이트
$ sudo apt update

// CodeDeploy Agent가 Ruby 환경에 의존하여 Ruby 설치
$ sudo apt install ruby-full

// 설치 스크립트를 다운로드하기 위한 wget 설치
$ sudo apt install wget

// 설치 스크립트를 저장할 디렉토리 이동 (원하는 경로로 이동해도 무관합니다.)
$ cd /home/ubuntu

// CodeDeploy Agent 설치 스크립트를 AWS S3에서 다운로드 (서울 리전)
$ wget https://aws-codedeploy-ap-northeast-2.s3.ap-northeast-2.amazonaws.com/latest/install

// 다운로드한 스크립트에 실행 권한 부여
$ chmod +x ./install

// CodeDeploy Agent 자동 설치, 설치 로그는 /tmp/logfile에 저장
$ sudo ./install auto > /tmp/logfile

`EC2 서버`에 접속하여 해당 명령어를 차례대로 입력합니다.

$ sudo service codedeploy-agent status

설치 후 `CodeDeploy Agent`가 설치 되었는지, 실행중인지 확인합니다.

`CodeDeploy Agent`가 정상적으로 동작중이라면 다음과 같은 내용이 출력됩니다.

1-2. Java 설치

`EC2 서버`에 `Java`언어를 설치하지 않았다면 설치해주도록 합니다.

$ sudo apt install openjdk-21-jdk
$ java --version

본인의 버전에 맞는 java언어를 설치하고, 설치 후 버전확인을 통해 설치가 되었는지 확인합니다.

2. AWS IAM 설정

`IAM 사용자`는 `GitHub Actions`가 `AWS에 접근`할 수 있도록 해주는 `인증 주체`입니다.

`GitHub Actions`를 통해 배포 자동화 시 `IAM 사용자`의 `AccessKey`와 `SecretAccessKey`를 통해 인증하여 AWS 리소스 `S3, CodeDeploy`에 접근하게 됩니다.

AWS에 접근 후 `IAM 사용자`의 `Key`를 통해 실행 명령을 내리고 사전에 `IAM 역할`이 부여된 `S3`와 `CodeDeploy`는 리소스 요청을 통해 AWS내에서 배포작업이 이루어지게 됩니다.

따라서 `IAM 사용자를 생성`하여 `GitHub Actions`에 `Secret`으로 설정하여 `GitHub Actions가 AWS에 접근하여 리소스를 요청`할 수 있도록 하고,

이후 `CodeDeploy`, `S3`가 자동화된 배포를 수행할 수 있도록 `IAM 역할을 부여`하는 방법에 대해 알아보도록 하겠습니다.

2-1. IAM 사용자 생성

`좌측 상단 검색`을 통해 `IAM` 서비스로 이동합니다.

서비스 이동 후, 좌측 메뉴바에서 `액세스 관리` → `사용자`를 선택한 뒤, `사용자 생성` 버튼을 클릭합니다.

원하는 `사용자 이름`을 입력하고 `다음` 버튼을 클릭합니다.

AmazonS3FullAccess
AWSCodeDeployFullAccess
AWSCodeDeployRole

권한 설정 탭에서 `직접 정책 연결`을 선택하고 위의 3가지 권한을 추가합니다.

AmazonS3FullAccess
- `S3 서비스`에 대한 `전체 권한`을 부여합니다.
- `GitHub Actions`에서 빌드된 zip 파일을 `S3에 업로드`하고, `CodeDeploy`가 이 파일을 다운로드 할 때 사용됩니다.
AWSCodeDeployFullAccess
- `CodeDeploy 서비스`에 대한 `전체 권한`을 부여합니다.
- `GitHub Actions`에서 BuildAndDeploy.yml이 실행되면 CodeDeploy를 트리거하고 `배포 작업을 시작`할 때 사용됩니다.
AWSCodeDeployRole
- `CodeDeploy` 역할에 필요한 권한을 부여합니다.
- `EC2 인스턴스`에서 `CodeDeploy Agent`가 `배포 작업을 수행`할 때 사용됩니다.

마지막으로 입력한 정보를 검토하고 `사용자 생성` 버튼을 클릭해 사용자 생성을 마칩니다.

2-2. IAM 사용자 AccessKey 생성

IAM 사용자를 생성한 뒤, 생성된 사용자를 선택하여 요약란의 `엑세스 키 만들기`를 클릭합니다.

해당되는 사용 사례를 선택합니다. 필자의 경우 `기타`를 선택하였습니다.

선택 후 `다음` 버튼을 클릭합니다.

선택사항입니다. `액세스 키 만들기` 버튼을 클릭하여 엑세스 키를 생성합니다.

엑세스 키를 생성한 후 `엑세스 키`와 `비밀 엑세스 키`가 나오는데 `두 가지 모두` 복사하여 보관 또는 .csv 파일을 보관합니다.

2-3. GitHub Actions Repository secrets에 IAM AccessKey 추가

GitHub Actions Repository secrets 추가 경로 이미지

GitHub에 접속하여 배포하고자 하는 Repository로 이동합니다.

이동 후 `Settings` → `Secrets and variables` → `Actions` → `New repository secret` 을 클릭합니다.

GitHub Actions Repository secrets 추가 이미지

사용하고자 하는 secret key 명을 입력하고 생성한 `IAM 사용자 AccessKey`를 입력합니다.

`AccessKey`, `SecretAccessKey` 두 가지 모두 생성합니다.

2-4. IAM 역할 생성

다시 `IAM 서비스`로 이동하여 좌측 메뉴의 `역할`을 선택하고 `역할 생성`을 클릭합니다.

`AWS 서비스` 선택 → 사용 사례 `EC2` 선택하고 `다음` 버튼을 클릭합니다.

AmazonS3FullAccess

`해당 권한을 검색`하여 선택하고 `다음` 버튼을 클릭합니다.

원하는 `역할 이름`을 입력하고 (설명 선택) 아래의 `역할 생성` 버튼을 클릭합니다.

2-5. EC2에 역할 부여

역할 생성을 마치고 생성한 EC2 인스턴스로 이동 및 선택하여 `작업` → `보안` → `IAM 역할 수정`을 선택합니다.

생성한 `IAM 역할`을 선택하고 `IAM 역할 업데이트`를 클릭합니다.

`IAM 역할 업데이트` 완료 후 `EC2 인스턴스 요약`에서 설정된 `IAM 역할`을 확인할 수 있습니다.

3. AWS S3 버킷 생성

`S3`는 배포 자동화 시 `GitHub Actions 워크플로우` 동작 시 `빌드 파일을 zip 형식`으로 S3에 저장하고,

저장된 파일을 `CodeDeploy Agent`가 다운로드 후 `appspec.yml`에 지정된 경로로 복사하는 저장소로 사용됩니다.

AWS S3 버킷 생성하는 방법에 대해 알아보도록 하겠습니다.

`좌측 상단 검색`을 통해 `S3 서비스`로 이동합니다.

이동 후 나오는 페이지에서 `버킷 만들기`를 클릭합니다.

원하는 `버킷 이름을 작성`하고 나머지 설정은 `기본 설정`으로 아래의 `버킷 만들기`를 클릭합니다.

4. AWS CodeDeploy 설정

AWS CodeDeploy는 AWS EC2, AWS ECS 등 컴퓨팅 시스템에 대한 애플리케이션 배포를 자동화 하여 제공하는 완전 관리형 서비스입니다.

지속적인 배포를 지원하는 대표적인 CD 도구로써 AWS CodeDeploy를 사용하게 되면 기존 운영중인 애플리케이션의 영향을 최소화 하면서 신속하게 배포할 수 있는 기능을 제공합니다.

4-1. CodeDeploy IAM 역할 생성

다시 `IAM 서비스`로 이동하여 `역할 생성`을 클릭합니다.

`AWS 서비스` → 사용 사례에 `CodeDeploy`를 검색하여 선택합니다.

사용 사례에 `CodeDeploy`를 선택 시 `AWSCodeDeployRole`이 권한 정책에 기본으로 추가되어 있습니다.

이 설정 그대로 `다음` 버튼을 클릭합니다.

사용하고자 하는 `역할 이름`을 작성하고 아래의 `역할 생성`을 클릭합니다.

4-2. 애플리케이션 생성

`좌측 상단 검색`을 통해 `CodeDeploy`를 검색하여 해당 서비스로 이동합니다.

좌측 메뉴에서 `애플리케이션` 클릭 → `애플리케이션 생성`을 클릭합니다.

사용하고자 하는 `애플리케이션 이름을 작성`하고 `컴퓨팅 플랫폼`으로 `EC2/온프레미스`를 선택한 뒤 `애플리케이션 생성` 버튼을 클릭합니다.

4-3. 배포 그룹 생성

생성한 애플리케이션을 선택하고 `배포 그룹 생성` 버튼을 클릭합니다.

사용하고자 하는 `배포 그룹 이름`을 입력하고 서비스 역할 입력란에 앞서 생성한 `CodeDeploy IAM 역할`을 선택합니다.

배포 유형으로 `현재 위치` 선택

환경 구성으로 `Amazon EC2 인스턴스` 선택 → `키 : Name (기본)`, `값 : 본인의 EC2 인스턴스`로 선택합니다. (배포에 사용하고자 하는 EC2 인스턴스)

AWS CodeDeploy 에이전트 설치 `한번만` 선택 → 배포 설정 `CodeDeployDefault.AllAtOnce` 선택 → 로드 밸런싱 활성화 체크 해제 `과금 요소`

설정을 마치고 `배포 그룹 생성` 버튼을 클릭합니다.

5. GitHub Actions 파이프라인 구성

AWS 인프라를 형성한 뒤, `GitHub Actions CI/CD 파이프라인` 구성에 대해 알아보도록 하겠습니다.

GitHub Actions 전체적인 파이프라인 구성은 다음과 같습니다.

CI 파이프라인
- `main 브랜치 push` 또는 `main`, `issue/**` (이슈 브랜치 모두)를 대상으로 `PR 생성` 트리거로 동작
- 코드 체크아웃
- Java 언어 설치
- Docker Compose 설치 및 실행
- 프로젝트 빌드 `code 컴파일 및 테스트`
- Docker Compose down `Docker 컨테이너 및 이미지 정리`
CD 파이프라인
- `CI completed` 트리거, 동작 조건 : `CI 통과`, `push`
- 코드 체크아웃
- Java 언어 설치
- GitHub Actions secrets에 추가한 값 prod환경 yml 파일의 환경변수로 주입
- Docker Compose 설치 및 실행
- `application-prod.yml` 기반 프로젝트 빌드 `code 컴파일 및 테스트`
- Docker Compose down `Docker 컨테이너 및 이미지 정리`
- `jar`, `appspec.yml`, `deploy.sh` 파일을 포함하여 `zip으로 생성`
- AWS 자격 증명 `IAM 사용자를 통한 AWS 리소스 접근`
- `S3 버킷`에 생성한 `zip 파일` 업로드
- AWS CodeDeploy를 사용하여 EC2 인스턴스에 애플리케이션 배포

필자의 경우 프로젝트 빌드 시 테스트가 이루어 질 때 로컬환경에서 테스트가 이루어지도록 Docker Compose를 파이프라인 구성에 추가하였습니다.

사용하지 않는다면 해당 부분은 건너뛰고 진행할 수 있습니다.

5-1. CI workflow 작성

`루트 경로`에 `.github/workflows/~.yml`파일을 생성합니다.

yml 파일은 `사용하고자 하는 파일명`으로 작성하되, 디렉토리 명은 위와 같이 생성해야 `github가 이를 인식하고 동작`합니다.

name: TodoBuildAndTest # 워크플로우 이름

on:
  push:
    branches:
      - main # main 브랜치 push 트리거
  pull_request:
    branches:
      - main
      - issue/** # main, issue/** 대상으로의 PR 생성 트리거

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    	# 코드 체크아웃
      - name: Checkout code
        uses: actions/checkout@v3

		# Java 언어 설치
      - name: Set up JDK 21
        uses: actions/setup-java@v3
        with:
          java-version: '21'
          distribution: 'temurin'
		
        # Docker Compose 설치
      - name: Install Docker Compose
        run: |
          sudo apt-get update
          sudo apt-get install -y docker-compose

		# Docker Compose 실행
      - name: Set up Docker Compose
        run: |
          docker-compose up -d
          docker-compose ps

		# 데이터베이스 작동까지 대기 5초단위로 재시도, 작동 후 10초 대기
      - name: Wait for services to be ready
        run: |
          until docker-compose exec -T mysql mysqladmin ping -h"127.0.0.1" --silent; do
            echo "Waiting for MySQL to be ready..."
            sleep 5
          done
          sleep 10

		# 프로젝트 빌드
      - name: Build with Gradle
        run: ./gradlew clean build -Duser.language=ko -Duser.country=KR

		# DockerCompose down (컨테이너 및 이미지 정리)
      - name: Tear down Docker Compose
        if: always() # CI 성공, 실패 여부와 관계없이 동작
        run: docker-compose down

`main push`, `issue/**, main 대상으로의 PR 생성` 시 트리거로 동작하는 workflow를 작성하였습니다.

위의 과정이 통과해야 CD workflow가 실행됩니다.

5-2. CD workflow 작성

`CI workflow`와 마찬가지로 `루트 경로`에 `.github/workflows/~.yml` 파일을 생성합니다.

name: TodoBuildAndDeploy # workflow 이름

# CI workflow 완료 시 트리거
on:
  workflow_run:
    workflows: [ "TodoBuildAndTest" ]
    types:
      - completed

jobs:
  deploy:
  
    # 조건 : CI가 통과해야하고 트리거는 push여야 한다.
    if: >
      github.event.workflow_run.conclusion == 'success' &&
      github.event.workflow_run.event == 'push'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
    
    	# 코드 체크아웃
      - name: Checkout code
        uses: actions/checkout@v3

		# Java 언어 설치
      - name: Set up JDK 21
        uses: actions/setup-java@v3
        with:
          java-version: '21'
          distribution: 'temurin'

		# GitHub Actions secrets에 설정한 값을 application-prod.yml 환경변수로 주입
      - name: Set Yaml
        uses: microsoft/variable-substitution@v1
        with:
          files: ./src/main/resources/application-prod.yml
        env:
          spring.datasource.url: ${{ secrets.MYSQL_URL }}
          spring.datasource.username: ${{ secrets.DB_USERNAME }}
          spring.datasource.password: ${{ secrets.DB_PASSWORD }}
          spring.data.redis.host: ${{ secrets.REDIS_HOST }}
          spring.data.redis.port: ${{ secrets.REDIS_PORT }}

		# Docker Compose 설치
      - name: Install Docker Compose
        run: |
          sudo apt-get update
          sudo apt-get install -y docker-compose

		# Docker Compose 실행
      - name: Set up Docker Compose
        run: |
          docker-compose up -d
          docker-compose ps

		# 데이터베이스 동작 대기 5초 간격으로 재시도, 동작 후 10초 대기
      - name: Wait for services to be ready
        run: |
          until docker-compose exec -T mysql mysqladmin ping -h"127.0.0.1" --silent; do
            echo "Waiting for MySQL to be ready..."
            sleep 5
          done
          sleep 10

		# application-prod.yml파일을 대상으로 프로젝트 빌드
      - name: Build with Gradle (prod profile)
        run: ./gradlew clean build -Dspring.profiles.active=prod -Duser.language=ko -Duser.country=KR

		# Docker Compose down (컨테이너 및 이미지 정리)
      - name: Tear down Docker Compose
        if: always() # 성공, 실패 여부와 상관없이 실행
        run: docker-compose down

		# gradlew 파일에 실행 권한 부여
      - name: Grant execute permission for gradlew
        run: chmod +x ./gradlew
        shell: bash

		# 빌드 파일, appspec.yml, deploy.sh 파일을 대상으로 zip 파일 생성 ($GITHUB_SHA : 현재 커밋의 고유한 해시 값)
      - name: Make Zip file
        run: zip -r $GITHUB_SHA.zip build/libs/*.jar appspec.yml scripts/deploy.sh
        shell: bash

		# AWS 자격 증명 (GitHub Actions가 AWS로 접근)
      - name: AWS credential setting
        uses: aws-actions/configure-aws-credentials@v3
        with:
          aws-region: ${{ secrets.AWS_REGION }}
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

		# S3 버킷에 생성한 zip 파일 업로드
      - name: Upload to S3
        run: aws s3 cp ./$GITHUB_SHA.zip s3://${{ secrets.AWS_S3_BUCKET }}/$GITHUB_SHA.zip

		# AWS CodeDeploy를 사용하여 EC2 인스턴스에 애플리케이션 배포
      - name: EC2 Deploy
        run: aws deploy create-deployment
          --application-name ${{ secrets.AWS_CODE_DEPLOY_APPLICATION }}
          --deployment-config-name CodeDeployDefault.AllAtOnce
          --deployment-group-name ${{ secrets.AWS_CODE_DEPLOY_GROUP }}
          --s3-location bucket=${{ secrets.AWS_S3_BUCKET }},key=$GITHUB_SHA.zip,bundleType=zip

`${{ secrets.~ }}`은 GitHub Actions secrets에 추가된 환경변수 입니다.

여기서 `Set Yaml`, `Mazk Zip file`, `AWS credential setting`, `Upload to S3`, `EC2 Deploy` 부분을 조금 더 자세히 설명하겠습니다.

Set Yaml
- `with`-`files`를 통해 환경변수로 등록한 `yml 파일 경로`를 지정합니다.
- GitHub Actions secrets에 추가한 값을 각 yml 파일에서 정의한 키 경로`depth`에 주입합니다.
- CD workflow 에서 환경변수에 값을 주입해 배포하여 EC2 서버에서는 값이 주입된 yml을 사용하게 됩니다.
Mazk Zip file
- `jar`, `appspec.yml`, `deploy.sh` 파일을 포함하여 $GITHUB_SHA.zip으로 생성합니다.
- `AWS S3에 업로드되는 파일명은 중복될 수 없습니다.` 그래서 `$GITHUB_SHA`(GitHub에서 제공하는 현재 커밋의 고유한 해시 값)를 사용하여 `현재 커밋된 값에 대한 고유한 파일명`을 생성합니다.
- 배포 시 `압축하고자 하는 파일의 경로`를 모두 지정해야 합니다.
AWS credential setting
- `AWS 리전`과 `IAM 사용자 생성 시 발급한 AccessKey`를 사용하여 `GitHub Actions`가 AWS 리소스에 접근`합니다.
- `AWS 리전`은 `배포 인프라 형성 시 설정했던 리전` 값을 등록합니다. `ap-northeast-2` (서울)
- 이 인증 정보는 `GitHub Actions`가 `S3 버킷 업로드`, `CodeDeploy 실행` 등 `AWS 리소스에 접근`할 때 사용됩니다.
- `EC2에 이미 역할이 부여`된 상태에서 `EC2 서버에서 직접 자격 증명`을 시도하는 경우 `자격 증명 오류`가 발생할 수 있습니다.
Upload to S3
- ${{ secrets.AWS_S3_BUCKET }} : 생성한 버킷의 이름
- S3에 생성한 zip 파일을 업로드 하는데, 업로드 경로는 `생성한 버킷의 이름`이 됩니다.
EC2 Deploy
- `aws deploy create-deployment` : AWS CLI 명령어로 CodeDeploy 배포 작업을 생성합니다.
- `--application-name ${{ secrets.AWS_CODE_DEPLOY_APPLICATION }}` : CodeDeploy에서 생성한 애플리케이션 이름을 지정합니다.
- `--deployment-group-name ${{ secrets.AWS_CODE_DEPLOY_GROUP }}` : CodeDeploy에서 생성한 배포 그룹 이름을 지정합니다.
- `--s3-location bucket=4{{ secrets.AWS_S3_BUCKET }}` : S3에 업로드된 애플리케이션 패키지의 위치를 지정합니다.
- 모든 과정은 `appspec.yml`, `deploy.sh` 파일 등에 작성한 규칙에 따라 `EC2 서버에서 애플리케이션이 배포`됩니다.

5-3. 배포 설정 파일 작성 (appspec.yml)

version: 0.0
os: linux

files:
  - source: /
    destination: /home/ubuntu/todo
    overwrite: yes

permissions:
  - object: /
    owner: ubuntu
    group: ubuntu

hooks:
  ApplicationStart:
    - location: scripts/deploy.sh
      timeout: 60

`appspec.yml` 파일은 `프로젝트의 루트 경로`에 생성합니다.

files
- `source` : 소스 디렉토리 경로를 지정합니다. `루트 경로`
- `destination` : EC2 인스턴스에서 복사될 파일이 저장될 위치를 지정합니다.
- `overwrite` : 이미 존재하는 파일을 덮어쓸지에 대한 여부를 지정합니다.
permissions
- `object` : 권한을 설정할 대상 파일이나 디렉토리를 지정합니다.
- `owner` : 파일의 소유자를 지정합니다.
- `group` : 파일이 속할 그룹을 지정합니다.
hooks
- 배포 작업 중 `특정 작업을 실행할 수 있는 위치`를 지정합니다.
- `location` : 실행할 스크립트`deploy.sh` 경로를 지정합니다.
- `timeout` : 스크립트 실행의 최대 시간을 지정합니다.

5-4. 배포 스크립트 작성 (deploy.sh)

#!/bin/bash

DEPLOY_PATH=/home/ubuntu/todo
echo ">>> 배포 경로: $DEPLOY_PATH" >> /home/ubuntu/deploy.log

mkdir -p $DEPLOY_PATH
echo ">>> 디렉토리 생성 완료" >> /home/ubuntu/deploy.log

BUILD_JAR=$(ls /home/ubuntu/todo/build/libs/*.jar)
JAR_NAME=$(basename $BUILD_JAR)
echo ">>> build 파일명: $JAR_NAME" >> /home/ubuntu/deploy.log

echo ">>> build 파일 복사" >> /home/ubuntu/deploy.log
cp $BUILD_JAR $DEPLOY_PATH 2>> /home/ubuntu/deploy_err.log

echo ">>> 현재 실행중인 애플리케이션 pid 확인 후 일괄 종료" >> /home/ubuntu/deploy.log
sudo ps -ef | grep java | awk '{print $2}' | xargs kill -15 2>> /home/ubuntu/deploy_err.log

DEPLOY_JAR=$DEPLOY_PATH/$JAR_NAME
echo ">>> DEPLOY_JAR 배포"    >> /home/ubuntu/deploy.log
echo ">>> $DEPLOY_JAR의 $JAR_NAME를 실행합니다" >> /home/ubuntu/deploy.log
nohup java -jar -Dspring.profiles.active=prod $DEPLOY_JAR >> /home/ubuntu/deploy.log 2>> /home/ubuntu/deploy_err.log &

`scripts/deploy.sh` 경로에 deploy.sh 파일을 생성합니다. 이는 `appspec.yml에서 지정한 경로`와 같습니다.

스크립트 동작 과정은 다음과 같습니다.

배포 경로 설정 및 로그 기록
배포 경로 디렉토리 생성
빌드된 jar 파일 찾기
빌드된 jar 파일 복사
실행중인 Java 애플리케이션 종료
jar 파일 배포 및 실행

각 작업의 진생 상황은 deploy.log에 기록되고 에러는 deploy_err.log에 기록됩니다.

$ cat /home/ubuntu/deploy.log
$ cat /home/ubuntu/deploy_err.log

`EC2서버`에서 해당 명령어를 통해 `진행상황과 에러 로그를 확인`할 수 있습니다.

6. GitHub Actions 테스트

인프라 구성과 배포 자동화 설정을 마치고 GitHub Actions에 트리거를 주어 실패 시, 성공 시에 대한 테스트를 통해 알아보도록하겠습니다.

6-1. CI workflow 실패 시

먼저 직접 코드 `컴파일 실패`를 유도하여 `CI workflow 실패` 시 `CD workflow` 가 동작하는지 테스트 해보도록 하겠습니다.

CI workflow 실패 시 CD workflow는 건너뛰어 실행되지 않는 모습을 볼 수 있습니다.

6-2 CI workflow 통과 시

다음으로 `CI workflow 통과` 시 `CD workflow 동작` 테스트 및 배포가 이루어 지는 과정에 대해 알아보겠습니다.

`CI workflow`가 정상적으로 통과되고 `CD workflow`가 동작한 모습을 볼 수 있습니다.

`CD workflow` 동작과정 중 `EC2 Deploy`가 수행된 상세내용을 확인해보면 `d-F6V9E6UW8`라는 배포 ID가 응답된 것을 확인할 수 있습니다.

해당 배포 ID를 통해 배포 상태를 추적할 수 있습니다.

`AWS CodeDeploy`로 이동해 배포 메뉴에 들어가 `응답된 배포 ID`를 검색하면 CodeDeploy 대시보드에 성공이 기록된 것을 확인할 수 있습니다.

6-3. AWS EC2 배포 확인

EC2 서버에 접속하여 디렉토리 내역을 조회해보면 `deploy.log`, `deploy_err.log` 로그 파일 및 `todo` 디렉토리가 생성된 것을 확인할 수 있습니다.

$ cat /home/ubuntu/deploy.log

진행상황 로그를 확인해보면 `deploy.sh` 스크립트에서 작성한 명령이 수행된 것을 확인할 수 있습니다.

오류 발생시 내역은 `deploy_err.log`에서 확인할 수 있습니다.

오류를 특정하기 어려울 시 `deploy.sh` 스크립트에 진행상황, 에러로그를 좀 더 세부적으로 작성하여 로그를 확인할 수 있습니다.

$ ps -ef | grep java

해당 명령어를 통해 애플리케이션 실행 여부를 확인할 수 있습니다.

또는 EC2 인스턴스의 `퍼블릭 IPv4 DNS`를 통해 직접 API 응답 테스트를 해볼 수 있습니다.

요청 시 정상적으로 응답되는 모습을 확인할 수 있습니다.

6-4. application-prod.yml 환경변수 주입 확인해보기

`CD workflow`에서 `yml 환경변수에 값을 주입`했었는데 직접 확인해보기 위한 방법을 알아보겠습니다.

먼저 `배포된 jar파일`이 있는 위치로 이동합니다.

$ jar xf jar파일명.jar

해당 명령어를 통해 jar 파일을 열 수 있습니다.

이후 `BOOT-INF` → `classes` 경로로 이동하면 yml 파일을 확인할 수 있습니다.

$ cat yml파일명.yml

해당 명령어를 통해 yml파일 내용을 확인하여 값이 주입되었는지 확인해 볼 수 있습니다.

7. 트러블 슈팅

7-1. CI/CD workflow 빌드 실패 - JVM 국가 및 언어 설정

`GitHub Actions CI/CD` 동작 중 테스트 코드가 실패해 중단되는 에러가 발생하였습니다.

해당 테스트코드의 경우 `Validation` 처리를 `default 메세지`로 처리하여 테스트코드를 작성한 부분이었는데,

Validation처리를 default 메세지로 처리할 경우 `빌드 시 JVM 기본 언어와 국가가 임의로` 설정되는 것을 알 수 있었습니다.

./gradlew clean build -Duser.language=ko -Duser.country=KR
./gradlew clean build -Dspring.profiles.active=prod -Duser.language=ko -Duser.country=KR

이를 해결하기 위해 빌드 시 `-Duser.language=ko`, `-Duser.country=KR` 명령어를 추가하여 JVM에서 기본 언어와 국가를 `대한민국으로 설정`하였습니다.

이 설정은 주로 애플리케이션이 로케일에 의존하는 기능 `ex) 에러 메세지, 날짜 형식, 숫자 형식 등`을 테스트하거나 실행할 때, 일관성을 유지하기 위해 사용됩니다.

해당 설정은 로케일에 의존적인 동작을 테스트하거나 특정 국가, 언어 환경에만 발생하는 문제를 디버깅할 때 도움이 될 수 있으며, 필요에 따라 추가적으로 설정하여 빌드 및 테스트 환경의 일관성을 유지할 수 있습니다.

로케일(locale)?
사용자의 언어, 국가뿐 아니라 사용자 인터페이스에서 사용자가 선호하는 사항을 지정한 매개 변수의 모임

7-2. 배포 실패 ApplicationStop - UnknownError

`CodeDeploy 서비스` → `배포 ID`를 선택하여 `View events`로 이동하면 배포과정을 확인할 수 있는데 첫 단계에서 오류가 발생하였습니다.

오류 코드 확인 결과

CodeDeploy agent was not able to receive the lifecycle event. Check the CodeDeploy agent logs on your host and make sure the agent is running and can connect to the CodeDeploy server.

위의 로그를 확인할 수 있는데 이 경우 먼저 `EC2 서버`에 `CodeDeploy Agent 재시작 후 실행중인지` 확인해봅니다.

$ sudo service codedeploy-agent restart # CodeDeploy Agent 재시작
$ systemctl status codedeploy-agent # CodeDeploy Agent 실행 확인

일반적으로 `EC2 인스턴스에 IAM role`을 부여하기 전, `CodeDeploy Agent`가 설치 및 실행되어 `IAM 역할`을 인식하지 못해 재시작 후 해결할 수 있습니다.

7-3. 배포 실패 ApplicationStop - AWS 자격 증명

위의 방법으로도 해결이 안되는 경우 `AWS 자격 증명`을 의심해 볼 수 있습니다.

기본적으로 자격증명이 제대로 이루어지지 않았거나, `EC2에 이미 역할이 부여`된 상태에서 `EC2 서버에 직접 자격 증명`을 시도했을 경우가 해당됩니다.

필자의 경우 위의 문제를 해결하기 위해 이것저것 시도해 보던 중, EC2에 직접 자격증명을 시도하여 문제가 발생하였습니다.

이는 위의 문제와 마찬가지로 `UnknownError`로 표시되어 에러가 발생한 이유를 제대로 파악하기 어렵습니다.

cat /var/log/aws/codedeploy-agent/codedeploy-agent.log

`EC2 서버`의 /var/log/aws/codedeploy-agent 경로에서 CodeDeploy Agent에서 배포 시 발생한 로그 파일이 존재하는데,

위의 명령어를 통해 배포 시 발생한 로그를 확인할 수 있습니다.

`ERROR [codedeploy- agent(1510)]`, `AccessDeniedException` 이 두 가지 키워드를 확인할 수 있었는데,

이는 `CodeDeploy Agent`가 인스턴스 서비스에 접근할 수 없다는 에러내용입니다.

일반적으로 `IAM 역할 권한 부족`, `CodeDeploy Agent 권한 문제`로 유추해 볼 수 있는데 필자의 경우 두가지 다 해당되지 않았고,

계속해서 찾아보던 중 EC2에 이미 역할이 부여된 상태에서 EC2 서버에서 직접 자격 증명을 시도했을 경우 자격 증명이 충돌하여 해당 에러가 발생할 수 있음을 알 수 있었습니다.

$ sudo rm -rf /root/.aws/credentials # AWS 자격증명 파일 삭제
$ sudo service codedeploy-agent restart # CodeDeploy Agent 재실행

해당 명령어를 통해 EC2 서버의 AWS 자격증명 파일을 삭제함으로써 해결할 수 있었습니다.

7-4. 배포 실패 BeforeInstall - UnknownError

해당 부분에서 `UnknownError` 에러가 발생하였습니다.

이는 간단하게 해결할 수 있는데 `CodeDeploy Agent 로그`를 확인하여

The CodeDeploy agent did not find an AppSpec file within the unpacked revision directory at revision-relative path \\\"appspec.yml\\\".

해당 로그를 찾을 수 있었습니다.

이는 `CodeDeploy Agent`가 `appspec.yml`파일을 찾을 수 없어 발생한 에러입니다.

배포시에는 CodeDeploy Agent가 자동화된 배포를 수행할 수 있도록 S3에 zip 파일 업로드 시 `jar`, `appspec.yml`, `deploy.sh` 파일을 함께 zip으로 생성해야 합니다.

마무리

GitHub Actions를 통한 CI/CD 와 AWS의 CodeDeploy, S3를 활용하여 배포 자동화 과정을 단계별로 상세히 알아보았습니다.

배포 과정 시 발생한 문제에 대한 해결도 함께 작성하였는데, 문제해결 시 AWS CodeDeploy 대시보드의 로그는 일반적인 오류의 원인을 파악하기에는 충분하지만, 구체적인 문제 해결을 위해 EC2 서버 내의 에러 로그를 추가적으로 확인하는 것이 중요하다고 생각됩니다.

'Server' 카테고리의 다른 글

[AWS] EC2, RDS, ElastiCache 인스턴스 생성부터 배포까지 (4)	2024.11.28
인증, 인가 세션(Session)과 토큰(Token)의 장단점과 차이점 (2)	2024.11.04
CSR과 SSR의 개념과 차이점 (feat. SPA, MPA) (4)	2024.09.11
REST API, RESTful API란? (2)	2024.08.30

동작 흐름

1. 초기 설정

1-1. CodeDeploy Agent 설치

1-2. Java 설치

2. AWS IAM 설정

2-1. IAM 사용자 생성

2-2. IAM 사용자 AccessKey 생성

2-3. GitHub Actions Repository secrets에 IAM AccessKey 추가

2-4. IAM 역할 생성

2-5. EC2에 역할 부여

3. AWS S3 버킷 생성

4. AWS CodeDeploy 설정

4-1. CodeDeploy IAM 역할 생성

4-2. 애플리케이션 생성

4-3. 배포 그룹 생성

5. GitHub Actions 파이프라인 구성

5-1. CI workflow 작성

5-2. CD workflow 작성

5-3. 배포 설정 파일 작성 (appspec.yml)

5-4. 배포 스크립트 작성 (deploy.sh)

6. GitHub Actions 테스트

6-1. CI workflow 실패 시

6-2 CI workflow 통과 시

6-3. AWS EC2 배포 확인

6-4. application-prod.yml 환경변수 주입 확인해보기

7. 트러블 슈팅

7-1. CI/CD workflow 빌드 실패 - JVM 국가 및 언어 설정

7-2. 배포 실패 ApplicationStop - UnknownError

7-3. 배포 실패 ApplicationStop - AWS 자격 증명

7-4. 배포 실패 BeforeInstall - UnknownError

마무리

'Server' 카테고리의 다른 글

티스토리툴바

5-3. 배포 설정 파일 작성 (appspec.yml)