프로젝트 관리 심화: 챕터 2 (CI/CD)

 

 

🗨️ CI/CD

📌 CI/CD의 개념을 이해하고, 이를 실제 프로젝트에 적용하여 자동화된 빌드, 테스트, 배포 파이프라인을 구축하는 방법을 배워보겠습니다.

• CI/CD의 기본 개념
  • CI와 CD의 정의와 목적을 이해합니다.
  • CI/CD를 도입함으로써 얻을 수 있는 장점을 학습합니다.
• CI/CD 도구 소개
  • 다양한 CI/CD 도구들(GitHub Actions, Jenkins, GitLab CI 등)의 특징과 사용 사례를 알아봅니다.
  • GitLab를 이용한 CI/CD 파이프라인 구축
  • GitLab의 설정 파일 작성 방법을 익히고, 이를 활용하여 자동화된 빌드 및 배포 파이프라인을 구축합니다. 

• 배포 자동화
  • AWS와 같은 클라우드 플랫폼을 이용하여 CI/CD 파이프라인의 배포 단계를 자동화하는 방법을 학습합니다.

CI/CD 개요

CI/CD란?

• CI (Continuous Integration)
  • CI는 개발자가 변경한 코드를 자주 통합하고, 이 코드가 전체 시스템과 잘 어우러지는지 자동으로 테스트하는 프로세스입니다.
  • 코드 변경이 발생할 때마다 빌드 및 테스트를 수행하여 코드 품질을 유지하고 문제를 조기에 발견할 수 있습니다.
• CD (Continuous Delivery)
  • CD는 CI의 결과물을 사용자에게 자동으로 배포하는 프로세스를 포함합니다. 코드 변경이 통합되고 테스트를 통과하면, 이를 자동으로 스테이징 환경 또는 프로덕션 환경에 배포합니다.
  • 지속적인 배포(Continuous Deployment)는 CI/CD의 확장 개념으로, 승인 절차 없이 자동으로 프로덕션 환경에 배포하는 것을 의미합니다.

 

CI/CD의 장점

• 빠른 피드백
  • 코드 변경 후 즉각적인 빌드 및 테스트 결과를 확인할 수 있어, 개발자가 문제를 빠르게 인지하고 수정할 수 있습니다.
• 자동화된 프로세스
  • 빌드, 테스트, 배포 과정이 자동화되어 수동 작업을 줄이고, 인적 오류를 방지할 수 있습니다.
• 일관된 배포
  • 동일한 배포 프로세스를 통해 모든 환경(개발, 테스트, 스테이징, 프로덕션)에서 일관된 결과를 보장합니다.
• 높은 품질 유지
  • 코드 품질을 지속적으로 검증하고, 잠재적인 문제를 조기에 발견하여 품질을 유지할 수 있습니다.
• 개발 속도 향상
  • 자동화된 파이프라인을 통해 개발 주기를 단축하고, 새로운 기능을 빠르게 사용자에게 제공할 수 있습니다.

 

CI/CD 도구

GitHub Actions

• GitHub Actions는 GitHub 저장소에 직접 통합되어 있는 CI/CD 도구로, YAML 파일을 사용하여 워크플로우를 정의할 수 있습니다.
• 특징
  • GitHub 저장소와의 강력한 통합
  • 다양한 이벤트 기반 트리거
  • 풍부한 커뮤니티 및 Marketplace 지원
  • 무료 사용 가능 (제한된 런타임 제공)

Jenkins

• Jenkins는 오픈 소스 CI/CD 도구로, 플러그인을 통해 다양한 기능을 확장할 수 있습니다.
• 특징
  • 높은 커스터마이징 가능
  • 다양한 플러그인 지원
  • 분산 빌드 및 다중 플랫폼 지원
  • 대규모 프로젝트에 적합

GitLab CI

• GitLab CI는 GitLab과 통합된 CI/CD 도구로, GitLab 저장소를 기반으로 CI/CD 파이프라인을 설정할 수 있습니다.
• 특징
  • GitLab과의 통합
  • 강력한 파이프라인 편집기 제공
  • 자동화된 DevOps 수명 주기 관리
  • 클라우드 및 온프레미스 모두 지원

 

🗨️ Amazon ECS

Amazon ECS 개요

Amazon ECS란?

• AWS Elastic Container Service는 docker 애플리케이션을 쉽게 배포하고 운영할 수 있도록 지원하는 완전관리형 Container Orchestration 서비스
  • 컨테이너 오케스트레이션 (Container Orchestration): 수십~수백 개의 도커 컨테이너들이 문제없이 돌아가도록, 오케스트라 지휘자처럼 자동으로 배포, 복구, 확장(Scaling)을 총괄 지휘하는 관리 시스템입니다.
• Kubernetes와 같은 container Orchestration 서비스
• Kubernetes 보다 사용하기 쉽고, 비용적으로도 저렴하기 때문에 소/중 규모의 프로젝트에 널리 사용
• serverless로 구성할 수 있는데, 이렇게 하면 인스턴스(가성서버)를 구성하고 관리할 필요도 없음
  • 서버리스 (Serverless): 서버가 아예 없다는 뜻이 아니라, 개발자가 직접 가상 서버(EC2 등)를 세팅하고 관리하는 귀찮은 작업 없이 클라우드(AWS)가 알아서 서버 인프라를 띄워주는 기술

 

구조

• ECS는 크게 ECR, ECS Cluster, ECS Service, ECS Task로 이루어집니다.
  • ECR: Docker image 저장소
  • ECS Cluster: 컨테이너를 실행하기 위한 Cluster로 여러 인스턴스로 이루어집니다. 이 인스턴스에 Docker container가 분산 실행됩니다. Serverless로 할 경우에는 인스턴스도 필요가 없습니다.
  • ECS Server: Docker 애플리케이션의 실행 그룹입니다.
  • ECS Task: ECS Server에 실제로 실행되는 docker container들을 Task 라고 합니다.
  • 로드밸런서와, 모니터링, Auto Scaling 등의 요소도 있음. ECS를 이용하면 이런 요소들까지 자동으로 관리

🆚 ECS 컨테이너 실행 방식 (EC2 vs Fargate) 완벽 요약

1. 인스턴스(EC2) 직접 관리
   • 개념: 가상 서버의 운영체제(OS), 보안, 네트워크 등 기반 인프라 전체를 개발자가 직접 통제하고 관리하는 방식입니다.
   • 비유: "월세 내고 통째로 빌린 내 상가." 직접 청소/관리해야 하지만 내 맘대로 개조할 수 있고, 24시간 내내 장사할 때는 가성비가 좋습니다. (대규모/고정 트래픽용)
2. 서버리스(Fargate) 방식
   • 개념: 귀찮은 인프라 관리는 AWS에 전면 위임하고, 개발자는 오직 '도커 컨테이너(앱) 실행' 자체에만 집중하는 방식입니다.
   • 비유: "필요할 때만 빌려 쓰는 프리미엄 공유 오피스." 관리해 주는 직원이 있어 개발에만 집중할 수 있지만, 장기간 풀가동하면 요금이 비쌉니다. (소규모/변동성 트래픽용)

 

• Task definition
  • ECS의 최소 실행단위는 “Task”
  • “Service”는 Task가 두 개 이상 모인 것 
  • Task는 docker 애플리케이션
  • 어느 포트에서 몇 개의 도커 컨테이너를 어떤 이미지로 실행할지 애플리케이션 실행 정보가 필요함.
  • 이 정보를 저장하고 있는 것이 Task definition

 

🗨️ 실습 개요

• Gitlab을 사용하여 CI/CD를 실습합니다.
• Gitlab 파이프라인에서 build를 수행하여 AWS ECR에 도커 이미지를 등록하고 파이프라인의 deploy에서 ECS에 어플리케이션을 배포 합니다.

🗨️ GitLab

소개

• GitLab을 이용해서 CI/CD 환경을 구축하고 CI 과정을 자동화 합니다.
  • GitLab 프로젝트를 만들고 여기에 개발한 코드를 PUSH 합니다.
  • 그러면 GitLab은 코드 Push가 된 것을 확인하고 Docker Image를 생성 ECR에 등록합니다.
  • 이 Docker Image로부터 docker container를 ECS에 실행하게 됩니다.

 

GitLab 가입 및 그룹, 프로젝트 생성

• GitLab 사이트에 가입
  • https://about.gitlab.com/ 페이지에서 gitlab 서비스에 가입을 합니다.
• GitLab에 그룹을 생성하고 블랭크 프로젝트를 생성

 

spring 프로젝트 생성 및 준비(GtiLab 연동)

스프링 프로젝트를 생성하여 IDE에서 열고 GitLab과 연동합니다.

• 스프링 프로젝트 생성

• Gitlab 프로젝트에 들어가서 Code 버튼을 클릭하여 Clone with HTTPS 안에 텍스트를 복사

• 프로젝트 연동 원격 정의 URL에 위의 주소를 붙여 넣습니다.

• 프로젝트를 풀합니다. 만약 풀을 클릭하여 나온 창에 main 이라는 브랜치가 안 나온다면 IDE를 종료하고 다시 실행합니다.

• 프로젝트에 컨트롤러를 생성합니다. (src/main/java/com/spring/sample/SampleController.java)

package com.spring.sample;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class SampleController {

    @GetMapping("/sample")
    public String sample() {
        return "Hello World";
    }
}

• application.properties를 수정합니다. (src/main/resources/application.properties)

spring.application.name=sample

server.port=8080

• 루트에 Dockerfile을 생성합니다. (Dockerfile)

FROM openjdk:17-jdk-slim

VOLUME /tmp

ARG JAR_FILE=build/libs/*.jar

COPY ${JAR_FILE} app.jar

ENTRYPOINT ["java","-jar","/app.jar"]

 

🗨️ AWS 보안그룹 추가

📌 외부에서 컨테이너에 접속할 수 있도록 포트을 열어줍니다.

• EC2 페이지에 접근하여 보안 그룹을 클릭합니다.

• 생성되어 있는 보안 그룹의 아이디를 클릭합니다.

• 인바운드 규칙 편집을 클릭하고 8080포트와 80 포트를 추가합니다.
  • 두 포트 모두 0.0.0.0/0 을 입력해줍니다.

🛡️ AWS 인바운드 규칙 설정 (포트와 0.0.0.0/0) 핵심 요약

1. 80과 8080 포트를 여는 이유: 80번 포트는 일반적인 인터넷 웹(HTTP) 접속을 위한 '기본 대문'이고, 8080번 포트는 우리가 만든 스프링 부트 서버가 손님을 기다리는 '전용 방문'이기 때문입니다.
2. 0.0.0.0/0의 진짜 의미 (완전 개방): "전 세계 어떤 컴퓨터(IP)에서 접속하든 모두 허락하겠다"는 뜻입니다. 여기서 뒤에 붙은 /0은 네트워크 제한 범위를 정하는 문법(CIDR)인데, 숫자가 0이면 '아무런 제한을 두지 않겠다(Anywhere)'는 의미가 됩니다.

 

🗨️ AWS ECR

📌 Amazon ECR은 AWS에서 제공하는 완전 관리형 docker image 저장소입니다. Amazon의 ECS, EKS, Elastic Beanstalk 등 여러 서비스와 통합될 수 있습니다. 배포하기 위해서는 일단 이미지를 ECR에 등록을 해야 합니다.

 

• AWS에 가입 후 ECR 대시보드에 접속합니다. 그 후 리포지토리 생성을 클릭합니다. 식별하기 쉽도록 리포지토리 이름을 깃랩의 그룹/리포지토리와 일치시킵니다.

• 생성한 리포지토리를 클릭하여 푸쉬 명령 보기를 클릭합니다. 이 명령어들은 깃랩 CI/CD에서 사용될 것입니다.

 

🗨️ AWS ECS

📌 Amazon ECS (Elastic Container Service)는 Amazon Web Services (AWS)에서 제공하는 완전 관리형 컨테이너 오케스트레이션 서비스입니다. 이는 Docker 컨테이너를 쉽게 실행, 정지, 관리할 수 있게 도와줍니다. 

 

• ECS 대시보드에 접속하여 클러스터 생성을 클릭합니다. 이름만 설정하고 인프라는 서버리스 선택 후 생성합니다.

• 태스크 정의 메뉴에서 새 태스크 정의 생성을 클릭합니다. 그리고 패밀리 이름을 입력해줍니다.

• 스크롤 하여 컨테이너에 정보를 입력합니다.
  • 이미지 URL에는 ECR의 리포지토리 URL을 입력합니다.
  • 포트에 80 포트를 8080으로 수정합니다.
  • 그 후 생성을 클릭합니다.

• 클러스터 메뉴로 돌아가서 생성된 클러스터를 클릭한 후, 서비스에서 생성을 클릭합니다.
  • 배포 구성에서 패밀리를 앞서 생성했던 태스크를 선택합니다. 서비스 이름도 입력해줍니다.

• 스크롤 하여 아래있는 로드 밸런싱에서 어플리케이션 로드 밸런싱을 선택합니다.
  • 정보는 아래와 같이 입력합니다. 포트는 80임을 확인합니다.

 

⚖️ 로드 밸런서(ALB)의 포트가 80인 이유

1. 80번 포트의 정체: "인터넷의 표준 대문"
   • 우리가 인터넷 브라우저에서 http://로 시작하는 웹사이트에 접속할 때, 브라우저는 사용자 몰래 기본적으로 80번 포트를 향해 찾아갑니다.
   • 즉, 일반 사용자들이 주소창 뒤에 :8080 같은 귀찮은 숫자를 붙이지 않고 깔끔하게 주소만 쳐서 들어오게 하려면, 밖으로 통하는 대문은 반드시 80번으로 열어두어야 합니다.
2. 로드 밸런서와 컨테이너의 완벽한 역할 분담
   • 로드 밸런서 (80번 대기): 식당의 '정문'입니다. 밖에서 오는 손님(트래픽)을 80번 문에서 가장 먼저 맞이합니다.
   • 스프링 부트 컨테이너 (8080번 대기): 식당의 '주방'입니다. 앞서 태스크 정의에서 서버가 일할 공간을 8080으로 설정했었죠.
   • 연결 과정: 로드 밸런서가 정문(80번)으로 들어온 트래픽을 안전하게 받아서, 뒤에서 묵묵히 일하고 있는 스프링 부트 주방(8080번)으로 토스(전달)해 주는 것입니다.

• 💡 한 줄 요약: "일반 사용자가 주소창에 포트 번호 없이 편하게 접속(HTTP 기본 포트 80)하게 만들고, 로드 밸런서가 이 요청을 받아서 내부의 스프링 부트 서버(8080)로 안전하게 토스해 주기 위한 설정입니다!"

 

🗨️ AWS IAM

• AWS IAM 에 접속하여 사용자 생성을 클릭합니다.
  • 직접 정책 연결을 클릭하여 AdministratorAccess 권한을 부여하여 사용자를 생성합니다.

• 생성한 사용자 상세페이지에 접속하여 액세스 키 만들기를 클릭합니다. 그 후 기타를 클릭합니다. 액세스 키가 만들어지면 .csv 파일 다운로드를 클릭하여 파일을 잘 가지고 있습니다 파일에는 엑세스에 관련된 키가 저장되어 있습니다.

 

🗨️ 깃랩 CI 파일 작성 및 푸쉬

• 깃랩 프로젝트 리포지토리 메뉴에서 Settings > CI/CD > Variables 를 클릭하고 2개 변수를 추가합니다.
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • ➡️ 이 두 키의 값은 아까 AWS IAM 에서 다운받은 csv에 있습니다.

🔐 GitLab CI/CD Variables & Expand 설정 핵심 요약

1. 프로젝트 Variables (변수)
   1. 역할: 코드에 직접 노출되면 위험한 '비밀 정보(AWS 접속 키, DB 비밀번호, API 토큰 등)'를 안전하게 보관하는 금고입니다.
   2. 이유: 소스 코드에 비밀번호를 그대로 적어서 올리면 해킹의 표적이 됩니다. 그래서 이곳에만 따로 등록해두고, CI/CD(자동 배포)가 실행될 때만 안전하게 가져다 쓰도록 격리해 두는 것입니다.
      • Protected
        → main/master 같은 보호 브랜치에서만 Variables 사용 가능하게 제한하는 옵션
        
      • Masked
        → CI/CD 로그에 비밀번호나 토큰 값이 노출되지 않도록 숨기는 옵션
      • ※ 실습 환경에서는 테스트 편의를 위해 옵션을 해제하고 사용
2. Expand variable reference (변수 확장 참조)
   • 역할: 입력한 값 안에 $ 기호가 있을 때, 이를 '또 다른 변수'로 해석할지 아니면 '그냥 특수문자 $'로 읽을지 결정하는 옵션입니다.
   • ✅ 체크할 때: 값 안에 다른 변수를 조합해서 쓸 때 (예: $USER_NAME이라고 적으면 실제 이름으로 변환해서 가져옴)
   • ❌ 체크 해제할 때 (매우 중요 🚨): 비밀번호나 키 값에 특수문자로 $가 포함되어 있을 때! 이 체크가 켜져 있으면 깃랩이 $ 뒤의 글자들을 변수로 착각해서 값을 엉뚱하게 망가뜨립니다. 따라서 비밀번호를 등록할 때는 꼭 체크를 해제해야 합니다.

 

• 프로젝트 루트 폴더에 .gitlab-ci.yml을 생성합니다. docker build 안에 스크립트는 ECR에서 푸쉬 명령 보기를 참고하여 작성합니다.
  • deploy 안에 있는 항목은 ECS의 생성 항목들 이름을 참고합니다.

services:
  - docker:stable-dind
  
# ⭐️ [핵심 1] 파이프라인 전체 3단계 흐름 (이 순서대로 작업이 진행됨)
stages:
  - build jar
  - build and push docker image
  - deploy
  
variables:
  APPLICATION_NAME: "01"
  TAG_NAME: "latest"
  DOCKER_IMAGE: "group-18934028/project-01"
  
build:
  image: openjdk:17-jdk-slim
  stage: build jar
  script:
    - chmod +x gradlew
    - ./gradlew clean build
    
  # ⭐️ [핵심 2] 파일 넘겨주기 (방금 만든 .jar 파일을 버리지 않고 다음 도커 작업으로 전달!)
  artifacts:
    paths:
      - build/libs/*.jar
      
docker build:
  image: docker:latest
  stage: build and push docker image
  rules:
    - if: $CI_COMMIT_BRANCH == "main" || $CI_COMMIT_REF_NAME == "main"
      variables:
        TAG_NAME: "latest"
    - if: $CI_COMMIT_BRANCH == "develop" || $CI_COMMIT_REF_NAME == "develop"
      variables:
        TAG_NAME: "develop"

  script:
    # 🗑️ 이 부분은 단순히 AWS 접속 도구를 다운로드하고 설치하는 명령어들입니다.
    - apk add --update --no-cache curl py3-pip py3-virtualenv
    - python3 -m venv /tmp/venv
    - source /tmp/venv/bin/activate
    - pip install awscli
    # ⭐️ [핵심 3] 비밀번호 숨겨서 쓰기! (깃랩에 등록한 보안키를 $ 기호로 불러와서 안전하게 세팅)
    - aws configure set aws_access_key_id $AWS_ACCESS_KEY_ID
    - aws configure set aws_secret_access_key $AWS_SECRET_ACCESS_KEY
    - aws configure set region ap-northeast-2
    
    # (도커 이미지를 만들고, AWS ECR 저장소 이름표를 붙인 뒤 밀어 올리는 핵심 작업들)
    - docker build -t $DOCKER_IMAGE .
    - docker tag $DOCKER_IMAGE:latest 730335597998.dkr.ecr.ap-northeast-2.amazonaws.com/$DOCKER_IMAGE:$TAG_NAME
    - aws ecr get-login-password --region ap-northeast-2 | docker login --username AWS --password-stdin 730335597998.dkr.ecr.ap-northeast-2.amazonaws.com
    - docker push 730335597998.dkr.ecr.ap-northeast-2.amazonaws.com/$DOCKER_IMAGE:$TAG_NAME

deploy:
  image: python:3.9-slim
  stage: deploy
  script:
    # 🗑️ 여기도 2단계와 마찬가지로 단순 도구 설치 과정입니다.
    - python3 -m venv /tmp/venv
    - source /tmp/venv/bin/activate
    - pip install awscli
    - aws configure set aws_access_key_id $AWS_ACCESS_KEY_ID
    - aws configure set aws_secret_access_key $AWS_SECRET_ACCESS_KEY
    - aws configure set region ap-northeast-2
    
    # ⭐️ [핵심 4] 대망의 자동 배포 버튼! (AWS ECS에게 "새 이미지 올라왔으니 강제로 서버 새로고침 해!" 라고 지시)
    - aws ecs update-service --cluster project-cluster --service project-01-service --task-definition project-01-task:1 --force-new-deployment

• IDE에서 프로젝트를 커밋, 푸쉬하여 반영합니다. 줄 구분 기호 경고가 나오면 그대로 커밋을 입력합니다.

• GitLab의 파이프라인을 확인합니다. 스테이지가 모두 성공하지 않으면 실패한 스테이지를 클릭하여 오류 내용을 확인합니다.

 

🚀 [CI/CD] GitLab + Docker + AWS(ECR/ECS) 자동 배포 흐름 정리

• 코드를 수정하고 Push만 하면, 빌드부터 AWS 서버 배포까지 모든 과정이 자동으로 이루어지는 CI/CD 파이프라인을 구축했습니다.

🌊 1. 전체 자동 배포 흐름 (Pipeline)

• git push 한 번으로 아래의 4단계가 자동으로 수행됩니다.

1. 내 PC: git push (GitLab으로 코드 전송)
2. GitLab CI/CD (build jar): Gradle로 Spring Boot 프로젝트 빌드
3. Docker (docker build & push): Docker Image 생성 후 AWS ECR에 업로드
4. AWS ECS (deploy): ECR에서 이미지를 Pull 받아 컨테이너 실행 (서버 재배포)

💡 2. 배포 과정 필수 핵심 개념

• Dockerfile: "이 프로젝트를 어떤 환경에서 어떻게 실행할지" 적어둔 실행 설명서.
• 베이스 이미지: 컨테이너 안의 "기본 컴퓨터 환경(Java/Linux)". (이게 없으면 Docker 컨테이너 자체를 만들 수 없음!)
• Docker Image: 실행에 필요한 코드 + Java + 설정 등을 전부 묶은 실행 패키지.
• AWS ECR: 완성된 Docker 이미지를 저장하는 저장소.
• AWS ECS: ECR에서 이미지를 가져와 컨테이너로 띄우고 관리하는 실행/관리 서비스.

🚨 트러블슈팅 (Troubleshooting) 핵심 정리

❌ OpenJDK 이미지 Pull 실패 (베이스 이미지 부재)

• 에러 메시지:

  manifest for openjdk:17-jdk-slim not found

• 원인: Docker Hub에 해당 이미지 태그(openjdk:17-jdk-slim)가 존재하지 않아 GitLab Runner가 이미지를 찾지 못함.
• 해결: Dockerfile과 GitLab CI에서 Java 베이스 이미지를 안정적인 eclipse-temurin:17-jdk로 변경.

build:
  image: eclipse-temurin:17-jdk
  stage: build jar
  script:
    - chmod +x gradlew
    - ./gradlew clean build
  artifacts:
    paths:
      - build/libs/*.jar

 

❌ ECS 이미지 Pull 실패 (브랜치명 불일치로 인한 Docker Build 스킵)

• 에러 메시지:

중지 코드: TaskFailedToStart
CannotPullContainerError: pull image manifest has been retried 7 time(s): failed to resolve ref ... :latest: not found

• 원인: ECS가 ECR에서 이미지를 가져오려 했으나 저장소가 비어있었음. 파이프라인 로그를 추적해 보니 전체 3단계 중 작업이 2개(build jar, deploy)만 실행되었음. 현재 GitLab 프로젝트의 기본 브랜치는 master인데, .gitlab-ci.yml의 실행 조건(rules)에는 main 브랜치만 설정되어 있어 중간의 Docker 이미지 빌드 및 ECR 업로드 단계가 통째로 스킵(Skip) 된 것이 근본 원인.
• 해결: .gitlab-ci.yml 파일의 docker build 작업 rules 조건에 master 브랜치를 명시적으로 추가하여, 코드를 푸시할 때 도커 빌드와 ECR 업로드가 정상적으로 수행되도록 수정.

docker build:
  image: docker:latest
  stage: build and push docker image
  rules:
    # 기존 main 조건 뒤에 master 브랜치 조건을 추가!
    - if: $CI_COMMIT_BRANCH == "main" || $CI_COMMIT_REF_NAME == "main" || $CI_COMMIT_BRANCH == "master" || $CI_COMMIT_REF_NAME == "master"
      variables:
        TAG_NAME: "latest"
    - if: $CI_COMMIT_BRANCH == "develop" || $CI_COMMIT_REF_NAME == "develop"
      variables:
        TAG_NAME: "develop"

 

❌ Docker 이미지 빌드 실패 (GitLab 환경 vs 실제 배포 환경의 차이)

• 증상: .gitlab-ci.yml의 자바 이미지를 수정하여 build jar 단계는 성공했으나, docker build 단계에서 다시 실패함.
• 원인: Java가 필요한 곳이 두 군데였는데 한 곳만 수정했기 때문.
  1. yml 파일: 코드를 빌드할 때 잠깐 빌려 쓰는 '임시 작업실'
  2. Dockerfile: 실제 AWS 서버에서 계속 돌아갈 '최종 실행 환경' 임시 작업실의 오류는 고쳤지만, 최종 실행 환경의 뼈대가 되는 Dockerfile의 베이스 이미지(openjdk:17)는 여전히 Docker Hub에서 찾을 수 없는 상태였음.
• 해결: Dockerfile의 FROM 구문 역시 안정적인 공식 배포판인 eclipse-temurin:17-jdk로 변경하여 해결.

FROM eclipse-temurin:17-jdk

VOLUME /tmp

ARG JAR_FILE=build/libs/*.jar

COPY ${JAR_FILE} app.jar

ENTRYPOINT ["java","-jar","/app.jar"]

 

 

🗨️ 확인하기

• ECS 대시보드에서 클러스터를 클릭하고 서비스 상세 페이지까지 접속합니다. 그 후 로드 밸런서 보기 버튼을 클릭합니다.

 

• 로드 밸런서 페이지에서 DNS 이름을 복사하여 웹에 입력하고 스프링 프로젝트의 엔드 포인트에 접근하여 결과를 확인합니다.

 

🗨️ 추가 정보) 깃허브 액션

• 인텔리제이 설정에서 깃허브를 로그인후 메뉴에서 VCS 또는 Git 메뉴에서 Github에 프로젝트 공유를 클릭하여 깃허브에리포지토리를 생성합니다.

• Actions 페이지에서 Ecs를 검색하고 “Configure”를 클릭합니다.

 

• 이후 나오는 페이지의 내용을 아래의 내용으로 대체 합니다.
  • 내용을 대체할 때, env 영역의 정보를 나의 AWS 정보로 대체하여 입력합니다. 그 후 “Commit changes” 버튼을 클릭합니다.

# This workflow will build and push a new container image to Amazon ECR,
# and then will deploy a new task definition to Amazon ECS, when there is a push to the "main" branch.
#
# To use this workflow, you will need to complete the following set-up steps:
#
# 1. Create an ECR repository to store your images.
#    For example: `aws ecr create-repository --repository-name my-ecr-repo --region us-east-2`.
#    Replace the value of the `ECR_REPOSITORY` environment variable in the workflow below with your repository's name.
#    Replace the value of the `AWS_REGION` environment variable in the workflow below with your repository's region.
#
# 2. Create an ECS task definition, an ECS cluster, and an ECS service.
#    For example, follow the Getting Started guide on the ECS console:
#      https://us-east-2.console.aws.amazon.com/ecs/home?region=us-east-2#/firstRun
#    Replace the value of the `ECS_SERVICE` environment variable in the workflow below with the name you set for the Amazon ECS service.
#    Replace the value of the `ECS_CLUSTER` environment variable in the workflow below with the name you set for the cluster.
#
# 3. Store your ECS task definition as a JSON file in your repository.
#    The format should follow the output of `aws ecs register-task-definition --generate-cli-skeleton`.
#    Replace the value of the `ECS_TASK_DEFINITION` environment variable in the workflow below with the path to the JSON file.
#    Replace the value of the `CONTAINER_NAME` environment variable in the workflow below with the name of the container
#    in the `containerDefinitions` section of the task definition.
#
# 4. Store an IAM user access key in GitHub Actions secrets named `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.
#    See the documentation for each action used below for the recommended IAM policies for this IAM user,
#    and best practices on handling the access key credentials.

name: Deploy to Amazon ECS

on:
  push:
    branches: [ "main" ]

env:
  AWS_REGION: ap-southeast-2                  # set this to your preferred AWS region, e.g. us-west-1
  ECR_REPOSITORY: group-18934028/test-01         # set this to your Amazon ECR repository name
  ECS_SERVICE: test-01-service                 # set this to your Amazon ECS service name
  ECS_CLUSTER: test-01-cluster                # set this to your Amazon ECS cluster name
  ECS_TASK_DEFINITION: .github/workflows/project-01-task-revision1.json # set this to the path to your Amazon ECS task definition
                                               # file, e.g. .aws/task-definition.json
  CONTAINER_NAME: test-01-container           # set this to the name of the container in the
                                               # containerDefinitions section of your task definition

permissions:
  contents: read

jobs:
  build:
    name: Build Jar
    runs-on: ubuntu-latest

    steps:
    - name: Checkout
      uses: actions/checkout@v4

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

    - name: Grant execute permission for gradlew
      run: chmod +x gradlew

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

    - name: Upload Build Artifacts
      uses: actions/upload-artifact@v3
      with:
        name: build-libs
        path: build/libs/*.jar

        
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    needs: build
    environment: production

    steps:
    - name: Checkout
      uses: actions/checkout@v4

    - name: Download Build Artifacts
      uses: actions/download-artifact@v3
      with:
        name: build-libs
        path: build/libs

    - name: Configure AWS credentials
      uses: aws-actions/configure-aws-credentials@v1
      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
      id: login-ecr
      uses: aws-actions/amazon-ecr-login@v1

    - name: Build, tag, and push image to Amazon ECR
      id: build-image
      env:
        ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
        IMAGE_TAG: ${{ github.sha }}
      run: |
        # Build a docker container and
        # push it to ECR so that it can
        # be deployed to ECS.
        docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
        docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG
        echo "image=$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG" >> $GITHUB_OUTPUT

    - name: Fill in the new image ID in the Amazon ECS task definition
      id: task-def
      uses: aws-actions/amazon-ecs-render-task-definition@v1
      with:
        task-definition: ${{ env.ECS_TASK_DEFINITION }}
        container-name: ${{ env.CONTAINER_NAME }}
        image: ${{ steps.build-image.outputs.image }}

    - name: Deploy Amazon ECS task definition
      uses: aws-actions/amazon-ecs-deploy-task-definition@v1
      with:
        task-definition: ${{ steps.task-def.outputs.task-definition }}
        service: ${{ env.ECS_SERVICE }}
        cluster: ${{ env.ECS_CLUSTER }}
        wait-for-service-stability: true

 

• 깃허브 프로젝트 루트에서 Code 버튼을 클릭하고 Codespaces 탭에서 Create codespace on main을 클릭하여 웹 IDE를 엽니다. (이 내용은 인텔리제이에서 해도 무방합니다.)

 

• .github/workflows 폴더에 project-01-task-revision1.json이라는 파일을 만듭니다. AWS의 테스크 정의 상세 페이지에서 JSON 탭을 클릭하여 클립보드로 복사 버튼을 클릭하여 내용을 복사합니다.
  • project-01-task-revision1.json 파일에 복사한 내용을 붙여넣기 하고 커밋, 푸쉬 합니다.
    1. 저 파일의 정체: CPU, 메모리, 열어둘 포트 등 서버를 어떻게 구동할지 명시해 둔 'ECS 서버 실행 설계도'입니다.
    2. AWS에 있는데 굳이 GitHub에 넣는 이유: 배포의 주도권이 AWS에서 GitHub로 넘어왔기 때문입니다. 자동화 툴인 GitHub Actions가 원격으로 AWS 서버를 조종하여 새 버전을 띄우려면, 그 '실행 기준 템플릿'을 자신의 저장소 내부에 직접 들고 있어야 명령을 내릴 수 있습니다.
  • "즉, AWS에 있는 기존 설정을 그대로 떠와서, GitHub가 배포할 때마다 '이 설계도(JSON) 설정 그대로 방금 만든 새 이미지를 실행해 줘!'

• 깃허브 리포지토리의 Settngs > Secrity > Secrets and variables > Actions의 페이지에서 Secrets 탭에서 새로운 시크릿을 입력합니다.
  • AWS IAM 에서 생성한 엑세스 키의 값을 넣어주며 2개를 생성합니다.
  • AWS_ACCESS_KEY_ID , AWS_SECRET_ACCESS_KEY

 

• 이제 Actions 탭의 workflow 를 실행하고 Gitlab에서와 같이 웹에서 로드 밸런서의 DNS 이름으로 접속하여 배포를 확인합니다.

 

🚀 [CI/CD] GitHub Actions + Docker + AWS (ECR/ECS) 자동 배포 파이프라인 구축

 

🌊 1. 전체 자동 배포 워크플로우 (Workflow Flow)

• GitLab의 Pipeline에 해당하는 GitHub의 워크플로우 실행(Workflow Run) 순서입니다. git push 한 번으로 아래 과정이 자동으로 진행됩니다.

1. 💻 GitHub Push: 개발자가 코드를 main 또는 master 브랜치에 푸시
2. 🛠️ Build Job: GitHub Runner가 임시 환경(JDK 17)을 띄우고 ./gradlew clean build 실행
3. 📦 Artifact 임시 저장: 빌드된 .jar 파일을 다음 배포 단계로 넘기기 위해 보관 (upload-artifact)
4. 🔐 AWS 인증: GitHub Secrets에 숨겨둔 자격 증명(ACCESS_KEY)으로 안전하게 로그인
5. 🐳 Docker Build & Push: Dockerfile을 기반으로 이미지를 만들고 AWS ECR(저장소)에 업로드
6. 📄 Task Definition 갱신: AWS ECS 실행 설계도(JSON)의 이미지 주소를 방금 만든 새 이미지로 교체
7. 🚀 ECS Deploy: ECS 서비스가 새로운 설정으로 서버(컨테이너)를 자동 재배포

💡 2. 파이프라인 필수 핵심 개념 사전

• [GitHub & 빌드 관련]
  • .github/workflows/aws.yml: GitHub Actions의 자동화 스크립트. 언제, 어떤 순서로 동작할지 정의하는 핵심 설정 파일입니다.
  • Artifact (아티팩트): 파이프라인의 작업(Job) 간에 주고받는 결과물. 여기서는 앞서 빌드한 .jar 파일을 뒤의 도커 배포 단계로 넘겨주기 위해 사용했습니다.
  • GitHub Secrets: AWS 접속 키(ACCESS_KEY_ID 등)처럼 코드에 직접 노출되면 안 되는 민감한 환경 변수를 안전하게 보관하는 금고입니다.
• [Docker 환경 관련]
  • Dockerfile: Spring Boot 앱을 실행할 "리눅스 실행 환경 박스(컨테이너)"를 만드는 조리 설명서입니다.
  • eclipse-temurin:17-jdk: Docker Hub에서 제공하는 Java 17 실행용 리눅스 기반 베이스 이미지. 실제 ECS에서 Spring Boot를 실행할 때 뼈대로 사용됩니다.
• [AWS 인프라 관련]
  • ECR (Elastic Container Registry): 우리가 만든 Docker 이미지를 차곡차곡 보관하는 AWS 전용 저장소입니다.
  • ECS (Elastic Container Service): ECR에서 이미지를 꺼내와 실제 컨테이너 서버로 실행하고 관리해 주는 지휘자입니다.
  • Task Definition (태스크 정의): ECS가 컨테이너를 실행할 때 "어떤 이미지, 몇 번 포트, 얼만큼의 메모리"로 실행할지 적어둔 서버 실행 설계도(JSON)입니다.
  • Load Balancer DNS: 컨테이너는 재시작될 때마다 내부 IP가 계속 바뀝니다. 그래서 사용자가 IP 대신 언제나 변함없이 접속할 수 있도록 제공해 주는 고정 접속 주소(대문)입니다.

🆚 3. 한눈에 보는 비교 (GitLab CI/CD vs GitHub Actions)

• 두 플랫폼 모두 큰 흐름(Push 트리거 → 빌드 → Docker 생성 → ECR 업로드 → ECS 배포)은 완벽하게 동일합니다. 플랫폼과 문법의 차이만 존재할 뿐입니다.

구분	GitLab CI/CD	GitHub Actions
설정 파일 위치	최상단 .gitlab-ci.yml	.github/workflows/aws.yml
작업 단위 명칭	Pipeline (파이프라인)	Workflow Run (워크플로우 런)
작업 흐름 정의	stages 와 jobs로 구성	jobs 와 steps로 구성
비밀 변수 관리	Settings > CI/CD > Variables	Settings > Secrets and variables

📝 요약하자면: GitLab에서는 하나의 파이프라인 안에서 단계를 나누어 실행했다면, GitHub Actions에서는 .yml 파일을 읽어 정해진 작업(Job)과 세부 단계(Step)를 실행하는 방식입니다. 어떤 도구를 쓰든 CI/CD의 본질적인 아키텍처는 동일하다는 것을 배울 수 있었습니다!

 

🚨 트러블슈팅 (Troubleshooting) 핵심 정리

❌ GitHub Actions 파이프라인 아예 실행 안 됨 (트리거 브랜치 불일치)

• 증상: 코드를 커밋하고 푸시(git push)했는데도 GitHub Actions 탭에 아무런 작업이 뜨지 않고 조용함.
• 원인: GitHub Actions는 설정 파일(.yml)의 실행 조건이 맞아야만 동작함. aws.yml 파일의 실행 조건(on: push)은 main 브랜치로 적혀 있었으나, 현재 깃허브의 실제 브랜치는 master였기 때문에 GitHub가 실행 조건이 아니라고 판단하여 아예 작동을 스킵한 것.
• 해결: aws.yml 안의 브랜치 조건을 branches: [ "master" ]로 수정하여 정상 작동 확인.

on:
  push:
    branches: [ "master" ]

❌ 파이프라인 중간 멈춤 (Artifact Action 구버전 만료)

• 에러 메시지:

  deprecated version of `actions/upload-artifact: v3`
  

• 원인: 빌드된 파일(.jar 등)을 임시로 저장해두는 GitHub의 기본 액션(upload-artifact) 버전이 구버전(v3)이었는데, GitHub 측에서 해당 버전의 지원을 강제로 종료(Deprecated)해버려서 발생한 시스템적 오류.
• 해결: aws.yml 코드 내부의 upload-artifact@v3와 download-artifact@v3를 모두 최신 버전인 @v4로 변경.

❌ ECS 최종 배포 실패 (Task Definition JSON 호환성 오류)

• 에러 메시지:

  Unexpected key 'enableFaultInjection'
  

• 원인: AWS 콘솔이 최근 업데이트되면서 ECS 설정 JSON 파일에 최신 옵션(enableFaultInjection: 인위적 장애 테스트용)을 자동으로 추가해서 발급해 줌. 하지만 GitHub Action의 배포 기능은 아직 이 최신 키워드를 인식하지 못해서 모르는 설정이 들어왔다며 에러를 뱉어낸 상황.
• 해결: 해당 기능은 단순 배포 흐름에 전혀 필요 없는 고급 옵션이므로, 프로젝트 내의 project-01-task.json 파일에서 해당 줄("enableFaultInjection": false,)을 찾아 삭제한 후 다시 푸시하여 최종 배포 성공!