mirror of
https://github.com/ktds-dg0501/kt-event-marketing.git
synced 2025-12-06 19:26:23 +00:00
e7ffdcfe44
- GitHub Actions workflow로 백엔드 서비스 자동 빌드/배포 구성 - Kustomize를 통한 dev/staging/prod 환경별 설정 관리 - 각 마이크로서비스별 Dockerfile 추가 - 배포 자동화 스크립트 및 환경 변수 설정 - CI/CD 가이드 문서 작성
289 lines
8.6 KiB
Markdown
289 lines
8.6 KiB
Markdown
# 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에 등록해야 합니다:
|
||
|
||
```bash
|
||
# 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. 초기 배포 테스트
|
||
|
||
```bash
|
||
# 로컬에서 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 워크플로우 테스트
|
||
|
||
```bash
|
||
# 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](./CICD-GUIDE.md) 참조
|
||
- 인프라 구조: [.github/README.md](../../.github/README.md) 참조
|
||
- 트러블슈팅: CICD-GUIDE.md의 트러블슈팅 섹션 참조
|
||
|
||
## 완료 체크리스트
|
||
|
||
- [x] Kustomize base 디렉토리 생성 및 매니페스트 복사
|
||
- [x] 환경별 overlay 디렉토리 생성 (dev/staging/prod)
|
||
- [x] 환경별 패치 파일 생성
|
||
- [x] GitHub Actions 워크플로우 작성
|
||
- [x] 배포 스크립트 작성
|
||
- [x] 환경별 설정 파일 작성
|
||
- [x] CI/CD 가이드 문서 작성
|
||
- [x] README 문서 작성
|
||
- [ ] GitHub Secrets 설정 (사용자 작업 필요)
|
||
- [ ] 초기 배포 테스트 (사용자 작업 필요)
|
||
- [ ] 워크플로우 동작 확인 (사용자 작업 필요)
|
||
|
||
---
|
||
|
||
**작성일**: 2025-10-29
|
||
**작성자**: Claude (DevOps Assistant)
|
||
**버전**: 1.0.0
|