🔧 CI/CD 파이프라인 구축

왜 CI/CD 파이프라인을 구축해야 할까?

어느 스타트업의 이야기입니다. 개발자 5명이 열심히 코드를 작성합니다. 기능 개발은 빠릅니다. 하지만 배포가 문제입니다.

매주 목요일 저녁, "배포 담당자"로 지정된 개발자가 다음 과정을 수동으로 수행합니다. 서버에 SSH 접속 → git pull → npm install → npm run build → PM2 재시작 → 브라우저에서 확인 → 문제 발생 시 롤백. 이 과정이 순조로우면 30분, 문제가 생기면 2시간입니다. 그리고 문제는 항상 생깁니다.

"내 로컬에서는 잘 됐는데..." 개발자라면 한 번쯤 해본 말입니다. 로컬 환경과 서버 환경의 Node.js 버전이 다르거나, 환경 변수 하나가 빠졌거나, 의존성 충돌이 발생하거나. 수동 배포는 인간의 실수를 허용하는 시스템입니다.

CI/CD 파이프라인은 이 모든 과정을 자동화합니다. 개발자가 git push를 하는 순간, 코드는 자동으로 빌드되고, 테스트를 통과하고, 스테이징 환경에 배포됩니다. 승인 버튼 하나를 클릭하면 프로덕션까지 자동 배포. 사람의 손이 닿을 일이 없으니 실수도 없습니다.

이 실습에서는 AWS의 4가지 개발자 도구를 조합하여 완전 자동화된 파이프라인을 직접 구축합니다:

• CodeCommit: 소스 코드 저장소 (Git 호스팅)
• CodeBuild: 빌드 및 테스트 자동화
• CodeDeploy: EC2/ECS에 코드 자동 배포
• CodePipeline: 위 3가지를 연결하는 오케스트레이터

파이프라인이 완성되면, git push 한 번으로 코드가 프로덕션까지 자동으로 흘러갑니다. "배포 담당자" 역할은 사라지고, 모든 개발자가 매일 안전하게 배포할 수 있게 됩니다.

아키텍처 개요

파이프라인 흐름

비용 예측

Step 1: CodeCommit 리포지토리 생성

CodeCommit은 AWS가 관리하는 프라이빗 Git 호스팅 서비스입니다. GitHub와 비슷하지만 AWS IAM과 완전히 통합되어 있어, AWS 계정의 인증/인가 체계를 그대로 사용할 수 있습니다. 팀원별로 특정 리포지토리에만 접근을 허용하는 것도 IAM 정책 하나로 가능합니다.

HTTPS(GRC) 자격 증명은 AWS 콘솔에서 IAM → 사용자 → 보안 자격 증명 탭에서 생성할 수 있습니다. Git 명령 실행 시 이 자격 증명으로 인증됩니다.

aws codecommit create-repository \
  --repository-name lab-cicd-app \
  --repository-description "CI/CD 파이프라인 실습용 리포지토리"
 
git clone https://git-codecommit.ap-northeast-2.amazonaws.com/v1/repos/lab-cicd-app
cd lab-cicd-app

Step 2: buildspec.yml 작성

buildspec.yml은 CodeBuild에게 "무엇을 어떤 순서로 실행할지"를 알려주는 설정 파일입니다. 4개의 빌드 단계(phase)가 순서대로 실행되며, 하나라도 실패하면 빌드가 중단됩니다. 각 단계의 역할을 명확히 이해하는 것이 중요합니다.

• install: 런타임 버전 지정과 의존성 설치. npm ci는 npm install보다 빠르고 재현성이 높습니다.
• pre_build: 테스트 실행. 테스트가 실패하면 빌드 자체가 중단되어 불량 코드가 배포되지 않습니다.
• build: 실제 빌드. React라면 npm run build, Next.js라면 next build 등을 실행합니다.
• post_build: 빌드 결과 정리. 타임스탬프 기록, 알림 전송 등에 사용합니다.

version: 0.2
phases:
  install:
    runtime-versions:
      nodejs: 18
    commands:
      - npm ci
  pre_build:
    commands:
      - echo "테스트 실행 중..."
      - npm test
  build:
    commands:
      - echo "빌드 시작: $(date)"
      - npm run build
  post_build:
    commands:
      - echo "빌드 완료: $(date)"
artifacts:
  files:
    - '**/*'
  base-directory: dist

Step 3: CodeBuild 프로젝트 생성

CodeBuild는 완전 관리형 빌드 서비스입니다. 빌드를 위한 서버를 직접 관리할 필요가 없습니다. 빌드가 실행될 때만 컨테이너가 생성되고, 빌드가 끝나면 자동으로 정리됩니다. Jenkins 서버를 직접 운영하는 것에 비해 관리 부담이 제로입니다.

빌드 환경 이미지로 amazonlinux2-x86_64-standard:5.0을 선택하면 Node.js, Python, Java, Go 등 대부분의 런타임이 사전 설치되어 있습니다. build.general1.small은 3 GB 메모리를 제공하며, 간단한 Node.js 빌드에 충분합니다.

aws codebuild create-project \
  --name lab-cicd-build \
  --source "type=CODECOMMIT,location=https://git-codecommit.ap-northeast-2.amazonaws.com/v1/repos/lab-cicd-app" \
  --environment "type=LINUX_CONTAINER,computeType=BUILD_GENERAL1_SMALL,image=aws/codebuild/amazonlinux2-x86_64-standard:5.0" \
  --service-role arn:aws:iam::<ACCOUNT_ID>:role/codebuild-service-role \
  --artifacts "type=S3,location=lab-cicd-artifacts"

Step 4: appspec.yml 작성

appspec.yml은 CodeDeploy에게 "파일을 어디에 복사하고, 배포 전후에 어떤 스크립트를 실행할지"를 알려주는 설정 파일입니다. buildspec.yml이 빌드 과정을 정의한다면, appspec.yml은 배포 과정을 정의합니다.

hooks 섹션의 라이프사이클 이벤트를 활용하면, 배포 전에 기존 서버를 안전하게 중지하고, 배포 후 의존성을 설치하고, 새 서버를 시작하는 것까지 자동화할 수 있습니다.

version: 0.0
os: linux
files:
  - source: /
    destination: /home/ec2-user/app
hooks:
  BeforeInstall:
    - location: scripts/stop_server.sh
      timeout: 300
  AfterInstall:
    - location: scripts/install_dependencies.sh
      timeout: 300
  ApplicationStart:
    - location: scripts/start_server.sh
      timeout: 300

Step 5: CodeDeploy 애플리케이션 생성

CodeDeploy는 EC2, ECS, Lambda 등 다양한 컴퓨팅 대상에 코드를 자동으로 배포하는 서비스입니다. 태그 기반으로 배포 대상 인스턴스를 지정하므로, Name=lab-server 태그가 붙은 EC2 인스턴스에만 코드가 배포됩니다.

배포 대상 EC2에는 CodeDeploy Agent가 미리 설치되어 있어야 합니다. Agent가 CodeDeploy 서비스와 통신하여 배포 명령을 수신하고 실행합니다.

aws deploy create-application \
  --application-name lab-cicd-deploy \
  --compute-platform Server
 
aws deploy create-deployment-group \
  --application-name lab-cicd-deploy \
  --deployment-group-name lab-deploy-group \
  --service-role-arn arn:aws:iam::<ACCOUNT_ID>:role/codedeploy-service-role \
  --ec2-tag-filters Key=Name,Value=lab-server,Type=KEY_AND_VALUE

Step 6: CodePipeline 연결

CodePipeline은 앞서 만든 CodeCommit, CodeBuild, CodeDeploy를 하나의 흐름으로 연결하는 오케스트레이터입니다. 소스 리포지토리에 변경이 감지되면 자동으로 파이프라인을 시작하고, 각 단계를 순서대로 실행합니다. 하나의 단계가 실패하면 이후 단계는 실행되지 않습니다.

Step 7: 수동 승인 단계 추가

수동 승인 단계는 프로덕션 배포 전 "마지막 관문" 역할을 합니다. 빌드가 성공하더라도 비즈니스 검증이나 QA 확인이 필요한 경우, 담당자가 확인 후 승인해야 다음 단계로 넘어갑니다. 승인 요청은 SNS를 통해 이메일이나 Slack으로 알릴 수 있습니다.

개발/스테이징 환경에서는 승인 단계를 생략하고, 프로덕션 파이프라인에만 추가하는 것이 일반적입니다. 이렇게 하면 개발 속도를 유지하면서도 프로덕션 안전성을 확보할 수 있습니다.

Step 8: 파이프라인 테스트

파이프라인이 완성되었으면 실제로 코드를 변경하여 전체 흐름을 검증합니다. 단순히 파이프라인이 "녹색"으로 성공하는지만 보는 것이 아니라, 배포된 EC2에서 실제 애플리케이션이 정상 동작하는지까지 확인해야 합니다.

트러블슈팅 가이드

핵심 개념 확인

완성 후 테스트 가이드

확장 아이디어

1. GitHub 소스 연동: CodeCommit 대신 GitHub를 소스로 연결합니다. GitHub App 또는 OAuth 토큰으로 연동할 수 있습니다.
2. 병렬 빌드: CodeBuild에서 여러 환경(Node 18, Node 20)의 빌드를 병렬로 실행하여 호환성을 검증합니다.
3. 슬랙 알림 연동: SNS → Lambda → Slack Webhook으로 빌드 성공/실패/승인 요청을 실시간 알림합니다.
4. Docker 이미지 빌드: buildspec.yml에서 Docker 이미지를 빌드하고 ECR에 push하는 과정을 추가합니다.
5. 멀티 환경 파이프라인: dev → staging → production 3단계 환경에 순차 배포하는 파이프라인을 구성합니다.

학습 정리

리소스 정리