🚀 GitHub Actions를 사용한 EKS 기반 Node.js 앱 배포 엔드투엔드 CI/CD 파이프라인
eksbanner
CI/CD Pipeline
📌 목차 (Table of Contents)
📂 저장소 구조 (Repository Structure)
이 저장소는 **모듈성(modularity)과 유지보수성(maintainability)**을 위해 구조화되어 있습니다:
📂 root
├── 📂 .github/workflows/ # GitHub Actions CI/CD 워크플로우
│ ├── ci.yml # 순수 CI 파이프라인 (테스트, 린팅, 보안)
...
🚀 최근 개선 사항 (Recent Improvements)
이 프로젝트는 현대적인 모범 사례와 보안 개선 사항으로 포괄적으로 향상되었습니다:
🔄 GitHub Actions Workflows
- ✅ 체계적인 워크플로우 구조(Organized Workflow Structure) - CI, 프로덕션 CD, 다중 환경 배포가 명확하게 분리됨
- ✅ 순수 CI 파이프라인(Pure CI Pipeline) - 테스트, 린팅(linting), 보안 스캐닝 수행 (ci.yml)
- ✅ 프로덕션 CD(Production CD) - ECR 통합 및 프로덕션 배포 담당 (cd-production.yml)
- ✅ 다중 환경 배포(Multi-Environment Deployment) - 버전 관리, Terraform, DNS 처리
- ✅ 명시적 권한 부여(Explicit Permissions) - 워크플로우별 최소 권한 원칙(Least-privilege)을 적용한 GITHUB_TOKEN 범위 설정
- ✅ 동시성 가드(Concurrency Guards) - 동일 타겟에 대한 중복 배포 방지 기능 제공
- ✅ 고정된 액션 버전(Pinned Action Versions) - @master 대신 릴리스 버전을 사용하도록 Trivy 고정 (pinning)
- ✅ 강화된 CI 파이프라인(Enhanced CI Pipeline) - fail-fast 비활성화와 함께 다중 노드 테스트(20.x, 22.x) 지원
- ✅ 보안 스캐닝(Security Scanning) - SARIF 업로드를 통한 Trivy 취약점 스캐닝 기능 제공
- ✅ EKS 1.31 - 향상된 애드온을 지원하는 지원 Kubernetes 버전
- ✅ 최신 프로바이더(Modern Providers) - AWS ~>5.50, Kubernetes ~>2.24, Helm ~>2.12 사용
- ✅ S3 네이티브 상태 잠금(S3-Native State Locking) - 더 이상 사용되지 않는 DynamoDB 락 테이블 제거 (Terraform >=1.10)
- ✅ 향상된 보안(Enhanced Security) - 암호화된 GP3 볼륨, 프라이빗 엔드포인트, CNI 정책 적용
- ✅ 개선된 태깅(Better Tagging) - 포괄적인 리소스 태깅 전략 구현
📦 Kustomize Configurations
- ✅ 이미지 관리(Image Management) - 단일
node-app 플레이스홀더를 사용하며, kustomize edit set image로 업데이트 가능
- ✅ 최신 구문(Modern Syntax) -
patches + labels (v5 호환, 더 이상 사용되지 않는 필드 없음)
- ✅ 안전한 오버레이(Safe Overlays) - 선택자/라벨 충돌 방지; 환경별 컨테이너 리소스 패치 적용
- ✅ 연결된 ConfigMaps(Wired ConfigMaps) - 생성된 앱 설정은
envFrom을 통해 마운트됨 (해시 처리 → 자동 롤아웃)
- ✅ 커밋되지 않은 시크릿(No Committed Secrets) - 시크릿은 kustomize 제너레이터가 아닌 별도의 프로세스(out-of-band)를 통해 프로비저닝됩니다.
🐳 도커 및 개발 환경 (Docker & Development)
- ✅ Node 22 Alpine: 지원되는 LTS 기반 이미지 (개발 및 운영 단계)
- ✅ 다단계 빌드 (Multi-Stage Builds): compose용
development 타겟, 배포용 production 타겟 사용
- ✅ 선택적 TLS 프록시 (Optional TLS Proxy): 자체 서명된 개발 인증서(self-signed dev certs)를 사용하는 compose 프로파일 하에 nginx 실행
- ✅ 상태 검사 (Health Checks): 애플리케이션, Redis 및 nginx (HTTPS 지원) 상태 검사 구현
- ✅ 요청 본문 제한 (Request Body Limits): 앱에서 10 KB 제한을 설정하여 과도한 페이로드로부터 보호
🔧 애플리케이션 및 코드 품질 (Application & Code Quality)
- ✅ XSS 방지 출력 (XSS-Safe Output): 사용자 입력 HTML은 렌더링 전에 모두 이스케이프 처리됨
- ✅ 엄격한 입력 유효성 검사 (Strict Input Validation): 정수만 허용;
12abc, 3.5, 1e3 등은 거부됨
- ✅ 98%+ 테스트 커버리지: 단위 테스트(Unit) + HTTP 통합 테스트 (총 28개 테스트, 80% 임계값 강제 적용)
- ✅ 보안 ESLint: eslintrc-legacy 설정을 사용한 security/import/promise 플러그인 적용
- ✅ 우아한 종료 처리 (Graceful Shutdown): 다운타임 제로(zero-downtime) 롤아웃을 위한 SIGTERM/SIGINT 핸들링 지원
🔧 사전 요구 사항 (Prerequisites)
진행하기 전에 다음 항목들이 설치되어 있는지 확인하십시오:
- 🛠 Node.js (>=20.x, LTS 권장)
- 🐳 Docker & Docker Compose
- 🏗️ Terraform (>=1.10.0 — S3 네이티브 상태 잠금(state locking)에 필수)
- ☸ kubectl (최신 버전)
- 🎭 Kustomize
- ☁ AWS CLI & eksctl
- ⚙️ GitHub Actions 설정 완료
- 🔑 EKS 관리용 AWS IAM 권한
- 🔒 보안 스캐닝 도구 (Trivy, CodeQL)
🔑 필수 GitHub Secret
| Secret | 사용처 | 목적 |
|---|
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY | cd-production, deployment | AWS 자격 증명 (EKS, ECR, Terraform) |
| ... | | |
💡 운영 환경의 경우, 장기 지속되는 AWS 접근 키보다 GitHub OIDC (id-token: write + IAM 역할 ARN) 사용을 권장합니다.
🏃♂️ 빠른 시작 (로컬 개발)
옵션 1: Docker Compose (권장)
git clone https://github.com/NotHarshhaa/CI-CD_EKS-GitHub_Actions.git
cd CI-CD_EKS-GitHub_Actions
...
옵션 2: 로컬 Node.js 개발
⚙️ CI/CD 워크플로우 (CI/CD Workflow)
**CI/CD 파이프라인(pipeline)**은 GitHub Actions를 사용하여 세 가지 전문화된 워크플로우로 구성됩니다:
🚀 CI 파이프라인 (ci.yml)
트리거: master, develop, staging으로의 푸시/PR
1️⃣ 코드 품질 검사(Code Quality Checks)
npm ci를 사용하여 Node.js 의존성(dependencies) 설치- 코드 품질 표준 준수를 위해 린팅(linting) 실행
2️⃣ 테스트 및 커버리지(Testing & Coverage)
- Node.js 18.x와 20.x 전반에 걸쳐 단위 테스트(unit tests) 실행
- Codecov 통합을 통해 커버리지 보고서(coverage reports) 생성
3️⃣ 보안 스캔(Security Scanning)
- 코드베이스에 Trivy 취약점 스캐너(vulnerability scanner) 실행
- **SARIF 결과(results)**를 GitHub Security 탭에 업로드
🚀 프로덕션 CD 파이프라인 (cd-production.yml)
트리거: master로의 푸시, 태그, 수동 배포
1️⃣ 빌드 및 푸시(Build & Push)
- 프로덕션 최적화가 적용된 Docker 이미지(image) 빌드
- SHA 태그 지정하여 Amazon ECR에 푸시
2️⃣ EKS 배포(Deploy to EKS)
- Kustomize를 사용하여 쿠버네티스 매니페스트(manifests) 업데이트
- 프로덕션 EKS 클러스터에 배포
3️⃣ 검증(Verification)
- 헬스 체크(Health checks) 및 스모크 테스트
- 배포된 이미지의 보안 스캔(Security scanning)
🌍 다중 환경 배포 (deployment.yml)
트리거: prod/dev/staging으로의 푸시, dev로의 PR
1️⃣ 버전 관리(Version Management)
- 커밋 메시지를 기반으로 한 시맨틱 버전 관리(Semantic versioning)
- 자동 태그 및 버전 파일 업데이트
2️⃣ 인프라 프로비저닝(Infrastructure Provisioning)
- Terraform을 사용한 EKS 클러스터 관리
- 다중 환경 인프라 설정
3️⃣ 애플리케이션 배포(Application Deployment)
- 각 환경에 대한 Docker 빌드
- 환경별 구성이 포함된 Kustomize 배포
- Cloudflare를 통한 DNS 관리(management)
4️⃣ 알림(Notifications)
- 배포 상태를 위한 Slack 통합(integration)
- 포괄적인 배포 보고
🚀 배포 작업 (Deployment Job)
1️⃣ Terraform 설정(Setup)
terraform init으로 Terraform 초기화.- 정확한 상태 관리(state management) 보장.
2️⃣ 인프라 프로비저닝 (Infrastructure Provisioning)
terraform plan을 실행하고, terraform apply를 실행합니다.- EKS 클러스터, 네트워킹 및 스토리지를 배포합니다.
3️⃣ Kubernetes 구성 (Kubernetes Configuration)
- 클러스터와 상호 작용하기 위해
kubectl을 구성합니다.
- 환경별 설정을 위해
Kustomize 오버레이를 적용합니다.
4️⃣ Ingress Controller 설정 (Ingress Controller Setup)
- Helm을 사용하여 NGINX Ingress를 설치합니다.
5️⃣ 애플리케이션 배포 (Application Deployment)
- 최신 Docker 이미지를 Kubernetes에 배포합니다.
- **Ingress 및 로드 밸런서(Load Balancer)**를 통해 서비스를 노출합니다.
🏗️ 인프라 상세 정보 (Infrastructure Details)
| 환경 | 인스턴스 유형 | 복제본 수 |
|---|
| Dev | t3.small | 1 |
| ... | | |
| ✅ Cloudflare를 통한 DNS 자동화 (DNS Automation via Cloudflare) | | |
- 환경별 서브도메인 (도메인은
CLOUDFLARE_DOMAIN 시크릿에 설정하세요):
dev.<your-domain>staging.<your-domain>prod.<your-domain>
📦 애플리케이션 배포 전략 (Application Deployment Strategy)
✅ 롤링 업데이트 (Rolling Updates) – 다운타임 제로(zero-downtime) 배포를 위해 maxUnavailable: 0 + 준비성(readiness)/활성 상태(liveness) 프로브 사용.
🔄 GitOps 원칙 (GitOps Principles)
✔ 진실의 원천으로서의 Git (Git as the Source of Truth)
✔ 선언적 인프라 (Declarative Infrastructure) (Terraform 및 Kubernetes)
✔ GitHub Actions를 통한 자동 배포 (Automated Deployments via GitHub Actions)
모든 인프라 변경은 Git 커밋을 통해 이루어져야 합니다.
🔒 보안 모범 사례 (Security Best Practices)
🔐 시크릿 관리 (Secrets Management)
- AWS Secrets Manager 및 GitHub Actions의 **암호화된 시크릿(encrypted secrets)**을 사용합니다.
🛡 컨테이너 보안 (Container Security)
- 취약점 스캔을 위해 Trivy와 Docker Bench Security를 사용합니다.
🚧 IAM 및 최소 권한 원칙 (IAM & Least Privilege)
- 제한된 접근 권한을 가진 **AWS IAM 역할(roles)**을 사용합니다.
📢 알림 및 경고 (Notifications & Alerts)
🔔 Slack 및 이메일 알림 (Slack & Email Notifications)
- CI/CD 작업 업데이트 – 파이프라인 상태 알림.
- DNS 업데이트 – 알림을 위한 Cloudflare 통합.
📡 모니터링 및 로깅 (Monitoring & Logging)
- 로그 및 메트릭을 위한 AWS CloudWatch.
- 관측 가능성(observability)을 위한 Prometheus 및 Grafana.
📊 모니터링 및 로깅 (Monitoring & Logging)
✅ 애플리케이션 로그 (Application Logs) – Fluent Bit을 사용하여 집계합니다.
✅ 인프라스트럭처 로그 (Infrastructure Logs) – AWS CloudWatch Logs에 저장됩니다.
✅ 메트릭 모니터링 (Metrics Monitoring) – Prometheus 및 Grafana를 사용하여 추적합니다.
📜 기여하기 (Contributing)
기여하고 싶으신가요? 방법은 다음과 같습니다:
- 저장소를 포크(Fork)하고 새 브랜치를 생성합니다.
- 변경 사항을 적용하고 설명이 포함된 메시지로 커밋(commit)합니다.
- 검토를 위해 풀 리퀘스트(Pull Request, PR)를 엽니다.
⭐ 지원 및 작성자 (Support & Author)
⭐ 별점 주기!
이 저장소가 유용하다고 생각하고 학습에 사용할 계획이라면, 별점(star)을 하나 주시는 것을 고려해 주세요 ⭐. 여러분의 지원은 제가 계속 개선하고 더 가치 있는 콘텐츠를 추가할 동기 부여가 됩니다! 🚀
이 프로젝트는 Harshhaa의 열정으로 제작되었습니다 💡.
여러분의 피드백을 듣고 싶습니다! 자유롭게 이슈(issue)를 열거나 개선 사항을 제안하거나, 토론을 위해 들러주세요. 함께 강력한 데브옵스(DevOps) 커뮤니티를 만들어 나갑시다!
📧 연결하기 (Let's Connect!)
저와 함께 계속 연결되어 더 많은 데브옵스 콘텐츠를 탐색해 보세요:
LinkedIn GitHub Telegram Dev.to Hashnode
📢 최신 정보 받기 (Stay Updated!)
최신 데브옵스(DevOps) 트렌드, 모범 사례 및 프로젝트 업데이트를 받아보고 싶으신가요? 제 블로그와 소셜 채널을 팔로우해 주세요!
Follow Me
