배경
기존에는 로컬에서 Docker 이미지 빌드 후 태그를 수동 지정하고 ECR에 push한 뒤, EC2에 접속해서 compose.yml을 수정하고 실행하는 방식이었다.
작업 자체는 단순했지만, 배포할 때마다 서버에 접속해야하는 번거로움이 있어 CI/CD를 적용하게 되었다.
CI/CD를 도입할 때 가장 먼저 고민해던 건 어떤 도구를 쓸것인가? 였다. 대표적으로 Jenkins, GitLab, Github Actions 등의 선택지가 있었는데, 결론적으로는 Github Actions를 선택했다.
이미 Github을 사용하고 있어 레포지토리 안에서 바로 자동화를 구성할 수 있다는 점과, Jenkins와 다르게 러너 기반이라 별도 인프라가 필요 없다는 점이 선택 이유였다.
Github Actions란?
레포지토리에 이벤트(push, PR 등)가 발생하면 해당 이벤트에 대해 정해진 동작을 수행할 수 있도록 하는 자동화 도구이다.
github actions의 구성 요소로는 workflow, event, job, step, action, runner가 있다.
Workflow
- github/workflows/* .yml 파일로 정의
- 자동화 전체 흐름
Event
- 워크플로우를 실행시키는 트리거
- push, PR 등
- 언제 실행할 것인가를 정의
Job
- 하나의 워크플로우 안에서 실행되는 작업 단위
- 여러개의 Job을 병렬/순차 실행 가능
Step
- Job 안에서 실행되는 개별 명령
- 실제 싱행되는 작업
Actions
- 재사용 가능한 작업 단위
- actions/checkout
- docker/build-push-action
- aws-actions/configure-aws-credentials
Runner
- 워크플로우가 실행되는 환경(서버)
- Github 제공
- 코드가 실제로 돌아가는 머신
Event 발생 → Workflow 실행 → Job이 순서대로 수행 → Step안에 Action들 실행
최종 아키텍처
on:
push:
branches:
- main # main 브랜치에 push 했을 때
workflow_dispatch: # Actions에서 수동 실행시
# 동시에 여러 배포가 겹치지 않도록 제어
concurrency:
group: deploy-ec2 # 동일 그룹 내에서는 하나만 실행
cancel-in-progress: false # 이전 작업을 취소하지 않고 순차 실행
# 공통 환경 변수
env:
AWS_REGION: ap-northeast-2 # AWS 리전
ECR_REPOSITORY: my-app # ECR 레포지토리 이름
jobs:
build-and-push:
name: Build and push to ECR
runs-on: ubuntu-latest # Github에서 제공하는 실행 환경
# 최소 권한 설정
permissions:
contents: read
# 다음 job에서 사용할 output 값 정의
outputs:
image: ${{ steps.image-uri.outputs.image }}
steps:
- name: Checkout
# 현재 레포지토리 코드를 runner로 가져옴
uses: actions/checkout@v4
- name: Configure AWS credentials
# Github Secrets에 있는 AWS 자격증명 사용
uses: aws-actions/configure-aws-credentials@v4
with:
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
aws-region: ${{ env.AWS_REGION }}
- name: Login to Amazon ECR
# Docker가 ECR에 push 가능하게 로그인
id: login-ecr
uses: aws-actions/amazon-ecr-login@v2
- name: Image URI
# 이미지 URI를 {레지스트리}/{리포지토리}:{GITHUB_SHA} 형태로 계산
id: image-uri
run: |
echo "image=${{ steps.login-ecr.outputs.registry }}/${{ env.ECR_REPOSITORY }}:${GITHUB_SHA}" >> "$GITHUB_OUTPUT"
- name: Set up Docker Buildx
# 멀티 플랫폼 빌드를 위한 Docker Buildx 설정
uses: docker/setup-buildx-action@v3
- name: Build and push
# Docker 이미지를 빌드하고 ECR로 push
uses: docker/build-push-action@v6
with:
context: . # 현재 디렉토리를 build context로 사용
file: Dockerfile # 사용할 Dockerfile
push: true # 빌드 후 바로 push
platforms: linux/amd64 # EC2 환경에 맞는 아키텍처
tags: ${{ steps.image-uri.outputs.image }}
# Github Actions 캐시 활용 -> 빌드 속도 향상
cache-from: type=gha
cache-to: type=gha,mode=max
deploy:
name: Deploy on EC2
needs: build-and-push # build-and-push job 완료 후 실행
runs-on: ubuntu-latest
steps:
- name: SSH deploy
# EC2 서버에 SSH로 접속하여 배포 실행
uses: appleboy/[email protected]
# 이전 job에서 만든 이미지 URI 전달
env:
FULL_IMAGE: ${{ needs.build-and-push.outputs.image }}
with:
host: ${{ secrets.EC2_HOST }} # EC2 주소
username: ${{ secrets.EC2_USERNAME }} # SSH 유저
key: ${{ secrets.EC2_SSH_PRIVATE_KEY }} # SSH 개인 키
envs: FULL_IMAGE
script: |
set -euo pipefail
# -e 에러 발생시 즉시 종료
# -u 정의되지 않은 변수 사용 시 에러
# -o pipefail 파이프라인 실패 감지
cd "${{ secrets.EC2_DEPLOY_DIR }}"
# docker-compose.yml이 있는 디렉토리로 이동
REGISTRY="${FULL_IMAGE%%/*}"
# FULL_IMAGE에서 레지스트리 부분만 추출
aws ecr get-login-password --region "${{ env.AWS_REGION }}" | docker login --username AWS --password-stdin "${REGISTRY}"
# EC2에서 ECR 로그인
# compose.yml의 image 태그만 최신 버전으로 교체
# 서비스 태그만 변경
sed -i -E "s|^([[:space:]]*image:[[:space:]]*.*\/name):[^[:space:]]+|\\1:${FULL_IMAGE##*:}|" compose.yml
docker compose pull
# 최신 이미지 pull
docker compose up -d
# 컨테이너 백그라운드 실행
docker image prune -f
# 사용하지 않는 이미지 삭제