kt-event-marketing/deployment/cicd/SETUP-SUMMARY.md

GitHub Actions CI/CD 파이프라인 구축 완료

작업 일시

2025-10-29

작업 내용

1. Kustomize 디렉토리 구조 생성 ✅

.github/kustomize/
├── base/                              # 기본 매니페스트 (35개 파일)
│   ├── kustomization.yaml            # 기본 리소스 정의
│   ├── cm-common.yaml
│   ├── secret-common.yaml
│   ├── secret-imagepull.yaml
│   ├── ingress.yaml
│   └── {service}-*.yaml              # 7개 서비스 × 4개 리소스
└── overlays/                          # 환경별 설정
    ├── dev/                           # Dev 환경 (9개 파일)
    │   ├── kustomization.yaml
    │   └── *-service-patch.yaml      # 7개 서비스
    ├── staging/                       # Staging 환경 (9개 파일)
    │   ├── kustomization.yaml
    │   └── *-service-patch.yaml      # 7개 서비스
    └── prod/                          # Prod 환경 (9개 파일)
        ├── kustomization.yaml
        └── *-service-patch.yaml      # 7개 서비스

총 파일 수: 62개

2. GitHub Actions 워크플로우 생성 ✅

파일: .github/workflows/backend-cicd.yaml

주요 기능:

• 변경된 서비스 자동 감지
• 병렬 빌드 및 테스트
• ACR에 Docker 이미지 푸시
• Kustomize를 사용한 AKS 배포
• 배포 검증 및 알림

트리거:

• develop 브랜치 push → dev 환경 자동 배포
• main 브랜치 push → prod 환경 자동 배포
• Manual workflow dispatch → 원하는 환경/서비스 선택 배포

Jobs:

1. detect-changes: 변경된 서비스 및 환경 감지
2. build-and-push: 서비스별 병렬 빌드 및 푸시
3. deploy: Kustomize 기반 AKS 배포
4. notify: 배포 결과 알림

3. 배포 스크립트 생성 ✅

디렉토리: .github/scripts/

1. deploy.sh

   • 로컬에서 수동 배포를 위한 메인 스크립트
   • 환경별 배포 설정 자동 적용
   • 사용법: ./deploy.sh <env> [service]

2. generate-patches.sh

   • Staging과 Prod 환경의 패치 파일 자동 생성
   • 리소스 할당량을 환경에 맞게 설정

3. copy-manifests-to-base.py

   • 기존 K8s 매니페스트를 base 디렉토리로 복사
   • namespace 선언 자동 제거

4. 환경별 설정 파일 생성 ✅

디렉토리: .github/config/

1. deploy_env_vars_dev

   • Dev 환경 변수 정의
   • Replicas: 1, CPU: 256m-1024m, Memory: 256Mi-1024Mi

2. deploy_env_vars_staging

   • Staging 환경 변수 정의
   • Replicas: 2, CPU: 512m-2048m, Memory: 512Mi-2048Mi

3. deploy_env_vars_prod

   • Prod 환경 변수 정의
   • Replicas: 3, CPU: 1024m-4096m, Memory: 1024Mi-4096Mi

5. 문서화 완료 ✅

1. deployment/cicd/CICD-GUIDE.md (15KB)

   • 전체 CI/CD 파이프라인 가이드
   • 사전 요구사항 및 설정 방법
   • 상세한 트러블슈팅 가이드
   • 모니터링 및 롤백 방법

2. .github/README.md (6KB)

   • CI/CD 인프라 구조 설명
   • 배포 프로세스 가이드
   • 환경별 설정 요약

3. deployment/cicd/SETUP-SUMMARY.md (이 파일)

   • 구축 완료 요약

시스템 정보

항목	내용
시스템명	kt-event-marketing
JDK 버전	21
빌드 도구	Gradle
ACR	acrdigitalgarage01.azurecr.io
AKS 클러스터	aks-digitalgarage-01
리소스 그룹	rg-digitalgarage-01
네임스페이스	kt-event-marketing
서비스 수	7개

서비스 목록

1. user-service (8081)
2. event-service (8082)
3. ai-service (8083)
4. content-service (8084)
5. distribution-service (8085)
6. participation-service (8086)
7. analytics-service (8087)

환경별 설정

환경	브랜치	이미지 태그	Replicas	CPU Limit	Memory Limit
Dev	develop	dev	1	1024m	1024Mi
Staging	manual	staging	2	2048m	2048Mi
Prod	main	prod	3	4096m	4096Mi

다음 단계 (Required)

1. GitHub Secrets 설정 필수

다음 Secrets를 GitHub Repository에 등록해야 합니다:

# ACR 자격증명 확인
az acr credential show --name acrdigitalgarage01

# Service Principal 생성
az ad sp create-for-rbac \
  --name "github-actions-kt-event-marketing" \
  --role contributor \
  --scopes /subscriptions/{subscription-id}/resourceGroups/rg-digitalgarage-01 \
  --sdk-auth

필수 Secrets:

1. ACR_USERNAME - ACR 사용자명
2. ACR_PASSWORD - ACR 패스워드
3. AZURE_CREDENTIALS - Service Principal JSON

등록 경로: GitHub Repository → Settings → Secrets and variables → Actions → New repository secret

2. 초기 배포 테스트

# 로컬에서 Kustomize 빌드 테스트
cd .github/kustomize/overlays/dev
kustomize build .

# Azure 로그인
az login

# AKS 자격증명 가져오기
az aks get-credentials \
  --resource-group rg-digitalgarage-01 \
  --name aks-digitalgarage-01

# Dev 환경 배포 테스트
./.github/scripts/deploy.sh dev

3. GitHub Actions 워크플로우 테스트

# develop 브랜치에 커밋하여 자동 배포 트리거
git checkout develop
git add .
git commit -m "ci: Add GitHub Actions CI/CD pipeline"
git push origin develop

또는 GitHub Actions UI에서 Manual workflow dispatch 실행

주요 특징

1. Kustomize 기반 환경 관리

• Base + Overlays 패턴으로 중복 최소화
• 환경별 리소스 할당량 자동 적용
• 이미지 태그 환경별 분리 (dev/staging/prod)

2. 자동 변경 감지

• Git diff를 통한 변경된 서비스 자동 감지
• 변경된 서비스만 빌드 및 배포하여 시간 절약
• Manual trigger 시 전체 또는 특정 서비스 선택 가능

3. 병렬 처리

• 7개 서비스를 병렬로 빌드하여 시간 단축
• Matrix strategy를 사용한 효율적인 CI

4. 안전한 배포

• Startup, Readiness, Liveness probe 설정
• 롤아웃 상태 자동 확인
• 배포 실패 시 자동 알림

5. 다단계 이미지 태깅

• 환경별 태그: dev/staging/prod
• Git SHA 태그: 추적성 확보
• latest 태그: 최신 버전 유지

파일 통계

카테고리	파일 수	설명
Kustomize Base	35	기본 매니페스트
Kustomize Dev Overlay	9	Dev 환경 설정
Kustomize Staging Overlay	9	Staging 환경 설정
Kustomize Prod Overlay	9	Prod 환경 설정
Workflows	1	GitHub Actions 워크플로우
Scripts	3	배포 및 유틸리티 스크립트
Config	3	환경별 설정 파일
Documentation	3	가이드 문서
Total	72	전체 파일

기술 스택

• CI/CD: GitHub Actions
• Container Registry: Azure Container Registry
• Orchestration: Azure Kubernetes Service (AKS)
• Manifest Management: Kustomize
• Build Tool: Gradle
• Runtime: OpenJDK 21
• Containerization: Docker (multi-stage builds)

참고 사항

현재 AKS 배포 상태

현재 7개 서비스가 모두 AKS에 배포되어 Running 상태입니다:

• user-service: 1/1 Running
• event-service: 1/1 Running
• ai-service: 1/1 Running
• content-service: 1/1 Running
• distribution-service: 1/1 Running
• participation-service: 1/1 Running
• analytics-service: 1/1 Running

기존 배포 방식과의 호환성

• 기존 K8s 매니페스트 (deployment/k8s/)는 그대로 유지
• Kustomize는 별도 경로 (.github/kustomize/)에 구성
• 두 방식 모두 사용 가능하나 CI/CD에서는 Kustomize 사용 권장

모니터링 및 로깅

• Kubernetes 기본 모니터링 사용
• Azure Monitor 통합 가능 (별도 설정 필요)
• Application Insights 연동 가능 (별도 설정 필요)

문의 및 지원

• CI/CD 관련 문제: deployment/cicd/CICD-GUIDE.md 참조
• 인프라 구조: .github/README.md 참조
• 트러블슈팅: CICD-GUIDE.md의 트러블슈팅 섹션 참조

완료 체크리스트

• Kustomize base 디렉토리 생성 및 매니페스트 복사
• 환경별 overlay 디렉토리 생성 (dev/staging/prod)
• 환경별 패치 파일 생성
• GitHub Actions 워크플로우 작성
• 배포 스크립트 작성
• 환경별 설정 파일 작성
• CI/CD 가이드 문서 작성
• README 문서 작성
• GitHub Secrets 설정 (사용자 작업 필요)
• 초기 배포 테스트 (사용자 작업 필요)
• 워크플로우 동작 확인 (사용자 작업 필요)

---

작성일: 2025-10-29 작성자: Claude (DevOps Assistant) 버전: 1.0.0