GitHub Actions CI/CD 파이프라인 및 Kustomize 다중 환경 배포 설정

- GitHub Actions workflow로 백엔드 서비스 자동 빌드/배포 구성 - Kustomize를 통한 dev/staging/prod 환경별 설정 관리 - 각 마이크로서비스별 Dockerfile 추가 - 배포 자동화 스크립트 및 환경 변수 설정 - CI/CD 가이드 문서 작성
2025-10-29 13:23:41 +09:00
parent 1b73d2880b
commit e7ffdcfe44
87 changed files with 4117 additions and 35 deletions
@@ -0,0 +1,582 @@
+# KT Event Marketing - Backend CI/CD Guide
+
+## 목차
+1. [개요](#개요)
+2. [아키텍처](#아키텍처)
+3. [사전 요구사항](#사전-요구사항)
+4. [GitHub Secrets 설정](#github-secrets-설정)
+5. [배포 환경](#배포-환경)
+6. [파이프라인 구조](#파이프라인-구조)
+7. [사용 방법](#사용-방법)
+8. [트러블슈팅](#트러블슈팅)
+
+---
+
+## 개요
+
+이 문서는 KT Event Marketing 백엔드 마이크로서비스의 CI/CD 파이프라인 구축 및 운영 가이드입니다.
+
+### 시스템 정보
+- **시스템명**: kt-event-marketing
+- **JDK 버전**: 21
+- **빌드 도구**: Gradle
+- **컨테이너 레지스트리**: Azure Container Registry (ACR)
+- **배포 대상**: Azure Kubernetes Service (AKS)
+
+### 서비스 목록
+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)
+
+---
+
+## 아키텍처
+
+### CI/CD 파이프라인 흐름
+
+```
+┌─────────────────┐
+│  Code Push      │
+│  (GitHub)       │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────────────────────────────────┐
+│  GitHub Actions Workflow                    │
+│                                              │
+│  1. Detect Changed Services                 │
+│  2. Build & Test (Gradle)                   │
+│  3. Build Docker Image                      │
+│  4. Push to ACR                             │
+│  5. Deploy to AKS (Kustomize)               │
+│  6. Verify Deployment                       │
+└─────────────────────────────────────────────┘
+         │
+         ▼
+┌─────────────────┐
+│  AKS Cluster    │
+│  (Running Pods) │
+└─────────────────┘
+```
+
+### Kustomize 디렉토리 구조
+
+```
+.github/
+├── kustomize/
+│   ├── base/                          # 기본 매니페스트
+│   │   ├── kustomization.yaml
+│   │   ├── cm-common.yaml
+│   │   ├── secret-common.yaml
+│   │   ├── ingress.yaml
+│   │   └── *-service-*.yaml          # 각 서비스별 리소스
+│   └── overlays/                      # 환경별 설정
+│       ├── dev/
+│       │   ├── kustomization.yaml
+│       │   └── *-service-patch.yaml  # Dev 환경 패치
+│       ├── staging/
+│       │   ├── kustomization.yaml
+│       │   └── *-service-patch.yaml  # Staging 환경 패치
+│       └── prod/
+│           ├── kustomization.yaml
+│           └── *-service-patch.yaml  # Prod 환경 패치
+├── workflows/
+│   └── backend-cicd.yaml              # GitHub Actions 워크플로우
+├── config/
+│   ├── deploy_env_vars_dev           # Dev 환경 변수
+│   ├── deploy_env_vars_staging       # Staging 환경 변수
+│   └── deploy_env_vars_prod          # Prod 환경 변수
+└── scripts/
+    └── deploy.sh                      # 수동 배포 스크립트
+```
+
+---
+
+## 사전 요구사항
+
+### 1. Azure 리소스
+- **Azure Container Registry (ACR)**
+  - 이름: acrdigitalgarage01
+  - SKU: Standard 이상
+
+- **Azure Kubernetes Service (AKS)**
+  - 클러스터명: aks-digitalgarage-01
+  - 리소스그룹: rg-digitalgarage-01
+  - Kubernetes 버전: 1.28 이상
+
+### 2. GitHub Repository Secrets
+다음 Secrets를 GitHub Repository에 등록해야 합니다:
+- `ACR_USERNAME`: ACR 사용자명
+- `ACR_PASSWORD`: ACR 패스워드
+- `AZURE_CREDENTIALS`: Azure Service Principal JSON
+
+### 3. 로컬 개발 환경 (수동 배포 시)
+- Azure CLI 2.50 이상
+- kubectl 1.28 이상
+- kustomize 5.0 이상
+- JDK 21
+
+---
+
+## GitHub Secrets 설정
+
+### 1. Azure Service Principal 생성
+
+```bash
+# Azure 로그인
+az login
+
+# 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
+
+# 출력된 JSON을 AZURE_CREDENTIALS Secret에 등록
+```
+
+### 2. ACR 자격증명 가져오기
+
+```bash
+# ACR 사용자명 확인
+az acr credential show --name acrdigitalgarage01 --query username
+
+# ACR 패스워드 확인
+az acr credential show --name acrdigitalgarage01 --query passwords[0].value
+```
+
+### 3. GitHub Secrets 등록
+
+GitHub Repository → Settings → Secrets and variables → Actions → New repository secret
+
+```
+Name: ACR_USERNAME
+Value: [ACR 사용자명]
+
+Name: ACR_PASSWORD
+Value: [ACR 패스워드]
+
+Name: AZURE_CREDENTIALS
+Value: [Service Principal JSON]
+```
+
+---
+
+## 배포 환경
+
+### Dev 환경
+- **브랜치**: develop
+- **이미지 태그**: dev
+- **네임스페이스**: kt-event-marketing
+- **리소스**:
+  - Replicas: 1
+  - CPU Request: 256m, Limit: 1024m
+  - Memory Request: 256Mi, Limit: 1024Mi
+
+### Staging 환경
+- **브랜치**: staging (Manual workflow dispatch)
+- **이미지 태그**: staging
+- **네임스페이스**: kt-event-marketing
+- **리소스**:
+  - Replicas: 2
+  - CPU Request: 512m, Limit: 2048m
+  - Memory Request: 512Mi, Limit: 2048Mi
+
+### Prod 환경
+- **브랜치**: main
+- **이미지 태그**: prod
+- **네임스페이스**: kt-event-marketing
+- **리소스**:
+  - Replicas: 3
+  - CPU Request: 1024m, Limit: 4096m
+  - Memory Request: 1024Mi, Limit: 4096Mi
+
+---
+
+## 파이프라인 구조
+
+### Job 1: detect-changes
+변경된 서비스를 감지하고 배포 환경을 결정합니다.
+
+**Output**:
+- `services`: 배포할 서비스 목록 (JSON 배열)
+- `environment`: 배포 대상 환경 (dev/staging/prod)
+
+**로직**:
+- Workflow dispatch: 사용자가 지정한 서비스와 환경
+- Push to main: 모든 서비스를 prod에 배포
+- Push to develop: 변경된 서비스를 dev에 배포
+
+### Job 2: build-and-push
+각 서비스를 병렬로 빌드하고 ACR에 푸시합니다.
+
+**단계**:
+1. 코드 체크아웃
+2. JDK 21 설정
+3. Gradle 빌드 (테스트 제외)
+4. 단위 테스트 실행
+5. bootJar 빌드
+6. ACR 로그인
+7. Docker 이미지 빌드 및 푸시
+
+**생성되는 이미지 태그**:
+- `{environment}`: 환경별 태그 (dev/staging/prod)
+- `{git-sha}`: Git 커밋 해시
+- `latest`: 최신 이미지
+
+### Job 3: deploy
+Kustomize를 사용하여 AKS에 배포합니다.
+
+**단계**:
+1. Azure 로그인
+2. AKS 자격증명 가져오기
+3. Kustomize 설치
+4. 이미지 태그 업데이트
+5. Kustomize 빌드 및 적용
+6. Deployment 롤아웃 대기
+7. 배포 검증
+
+### Job 4: notify
+배포 결과를 알립니다.
+
+---
+
+## 사용 방법
+
+### 1. 자동 배포 (Push)
+
+#### Dev 환경 배포
+```bash
+git checkout develop
+git add .
+git commit -m "feat: 새로운 기능 추가"
+git push origin develop
+```
+
+#### Prod 환경 배포
+```bash
+git checkout main
+git merge develop
+git push origin main
+```
+
+### 2. 수동 배포 (Workflow Dispatch)
+
+GitHub Actions 웹 UI에서:
+1. Actions 탭 클릭
+2. "Backend CI/CD Pipeline" 워크플로우 선택
+3. "Run workflow" 클릭
+4. 환경과 서비스 선택:
+   - Environment: dev/staging/prod
+   - Service: all 또는 특정 서비스명
+
+### 3. 로컬에서 수동 배포
+
+```bash
+# Dev 환경에 모든 서비스 배포
+./.github/scripts/deploy.sh dev
+
+# Prod 환경에 특정 서비스만 배포
+./.github/scripts/deploy.sh prod user-service
+
+# 스크립트 도움말
+./.github/scripts/deploy.sh
+```
+
+### 4. 단일 서비스 배포
+
+특정 서비스만 배포하려면:
+
+```bash
+# GitHub Actions UI에서 Workflow Dispatch 사용
+# 또는 로컬 스크립트 사용
+./.github/scripts/deploy.sh dev user-service
+```
+
+---
+
+## 배포 검증
+
+### 1. Pod 상태 확인
+```bash
+kubectl get pods -n kt-event-marketing
+```
+
+모든 Pod가 `Running` 상태이고 `READY` 컬럼이 `1/1`이어야 합니다.
+
+### 2. Service 확인
+```bash
+kubectl get svc -n kt-event-marketing
+```
+
+### 3. Ingress 확인
+```bash
+kubectl get ingress -n kt-event-marketing
+```
+
+### 4. 로그 확인
+```bash
+# 특정 Pod의 로그
+kubectl logs -n kt-event-marketing <pod-name>
+
+# 최근 로그 스트리밍
+kubectl logs -n kt-event-marketing <pod-name> -f
+
+# 이전 컨테이너 로그
+kubectl logs -n kt-event-marketing <pod-name> --previous
+```
+
+### 5. 애플리케이션 헬스 체크
+```bash
+# Ingress를 통한 헬스 체크
+curl http://kt-event-marketing-api.20.214.196.128.nip.io/api/v1/users/actuator/health
+
+# 각 서비스별 엔드포인트
+curl http://kt-event-marketing-api.20.214.196.128.nip.io/api/v1/events/actuator/health
+curl http://kt-event-marketing-api.20.214.196.128.nip.io/api/v1/content/actuator/health
+curl http://kt-event-marketing-api.20.214.196.128.nip.io/api/v1/ai-service/actuator/health
+curl http://kt-event-marketing-api.20.214.196.128.nip.io/distribution/actuator/health
+curl http://kt-event-marketing-api.20.214.196.128.nip.io/api/v1/participations/actuator/health
+```
+
+---
+
+## 트러블슈팅
+
+### 문제 1: ImagePullBackOff
+
+**증상**:
+```
+kubectl get pods -n kt-event-marketing
+NAME                           READY   STATUS             RESTARTS   AGE
+user-service-xxx               0/1     ImagePullBackOff   0          2m
+```
+
+**원인**:
+- ACR 인증 실패
+- 이미지가 ACR에 존재하지 않음
+
+**해결**:
+```bash
+# Secret 확인
+kubectl get secret kt-event-marketing -n kt-event-marketing
+
+# Secret 재생성
+kubectl create secret docker-registry kt-event-marketing \
+  --docker-server=acrdigitalgarage01.azurecr.io \
+  --docker-username=<ACR_USERNAME> \
+  --docker-password=<ACR_PASSWORD> \
+  -n kt-event-marketing \
+  --dry-run=client -o yaml | kubectl apply -f -
+
+# ACR에 이미지 존재 확인
+az acr repository list --name acrdigitalgarage01 --output table
+az acr repository show-tags --name acrdigitalgarage01 --repository kt-event-marketing/user-service
+```
+
+### 문제 2: CrashLoopBackOff
+
+**증상**:
+```
+kubectl get pods -n kt-event-marketing
+NAME                           READY   STATUS             RESTARTS   AGE
+user-service-xxx               0/1     CrashLoopBackOff   5          5m
+```
+
+**원인**:
+- 애플리케이션 시작 실패
+- 환경 변수 오류
+- 데이터베이스 연결 실패
+
+**해결**:
+```bash
+# Pod 로그 확인
+kubectl logs -n kt-event-marketing user-service-xxx
+
+# 이전 컨테이너 로그 확인
+kubectl logs -n kt-event-marketing user-service-xxx --previous
+
+# ConfigMap 확인
+kubectl get cm -n kt-event-marketing cm-common -o yaml
+kubectl get cm -n kt-event-marketing cm-user-service -o yaml
+
+# Secret 확인 (값은 base64 인코딩)
+kubectl get secret -n kt-event-marketing secret-common -o yaml
+
+# Pod describe로 상세 정보 확인
+kubectl describe pod -n kt-event-marketing user-service-xxx
+```
+
+### 문제 3: Readiness Probe Failed
+
+**증상**:
+```
+kubectl get pods -n kt-event-marketing
+NAME                           READY   STATUS    RESTARTS   AGE
+content-service-xxx            0/1     Running   0          3m
+```
+
+Pod는 Running이지만 READY가 0/1입니다.
+
+**원인**:
+- Actuator 엔드포인트 경로 오류
+- 애플리케이션 Context Path 설정 문제
+
+**해결**:
+```bash
+# Pod 이벤트 확인
+kubectl describe pod -n kt-event-marketing content-service-xxx
+
+# 수동으로 헬스 체크 테스트
+kubectl exec -n kt-event-marketing content-service-xxx -- \
+  curl -f http://localhost:8084/api/v1/content/actuator/health
+
+# Deployment의 probe 설정 확인 및 수정
+kubectl edit deployment content-service -n kt-event-marketing
+```
+
+### 문제 4: Database Connection Failed
+
+**증상**:
+로그에서 데이터베이스 연결 오류 발생
+
+**해결**:
+```bash
+# PostgreSQL Pod 확인
+kubectl get pods -n kt-event-marketing | grep postgres
+
+# PostgreSQL 연결 테스트
+kubectl exec -it distribution-postgresql-0 -n kt-event-marketing -- \
+  psql -U eventuser -d postgres -c "\l"
+
+# 데이터베이스 생성
+kubectl exec distribution-postgresql-0 -n kt-event-marketing -- \
+  bash -c "PGPASSWORD=Hi5Jessica! psql -U eventuser -d postgres -c 'CREATE DATABASE analytics_db;'"
+
+# ConfigMap과 Secret의 DB 설정 확인
+kubectl get cm cm-analytics-service -n kt-event-marketing -o yaml
+kubectl get secret secret-analytics-service -n kt-event-marketing -o yaml
+```
+
+### 문제 5: Workflow 실패
+
+**증상**:
+GitHub Actions 워크플로우가 실패합니다.
+
+**해결**:
+
+1. **Build 단계 실패**:
+```bash
+# 로컬에서 빌드 테스트
+./gradlew clean build
+
+# 특정 서비스만 빌드
+./gradlew user-service:build
+```
+
+2. **Docker push 실패**:
+- ACR_USERNAME, ACR_PASSWORD Secrets 확인
+- ACR에 로그인 권한 확인
+
+3. **Deploy 단계 실패**:
+- AZURE_CREDENTIALS Secret 확인
+- Service Principal 권한 확인
+- AKS 클러스터 접근 권한 확인
+
+### 문제 6: Kustomize 빌드 실패
+
+**증상**:
+```
+Error: unable to find one or more resources
+```
+
+**해결**:
+```bash
+# 로컬에서 Kustomize 빌드 테스트
+cd .github/kustomize/overlays/dev
+kustomize build .
+
+# 리소스 파일 존재 확인
+ls -la ../../base/
+
+# kustomization.yaml의 resources 경로 확인
+cat kustomization.yaml
+```
+
+---
+
+## 모니터링 및 로깅
+
+### 1. 실시간 로그 모니터링
+```bash
+# 모든 서비스 로그 스트리밍
+kubectl logs -n kt-event-marketing -l app.kubernetes.io/part-of=kt-event-marketing -f
+
+# 특정 서비스 로그
+kubectl logs -n kt-event-marketing -l app=user-service -f
+```
+
+### 2. 리소스 사용량 모니터링
+```bash
+# Pod 리소스 사용량
+kubectl top pods -n kt-event-marketing
+
+# Node 리소스 사용량
+kubectl top nodes
+```
+
+### 3. 이벤트 확인
+```bash
+# 네임스페이스 이벤트
+kubectl get events -n kt-event-marketing --sort-by='.lastTimestamp'
+
+# 특정 Pod 이벤트
+kubectl describe pod -n kt-event-marketing user-service-xxx
+```
+
+---
+
+## 롤백
+
+### 1. Deployment 롤백
+```bash
+# 이전 버전으로 롤백
+kubectl rollout undo deployment/user-service -n kt-event-marketing
+
+# 특정 리비전으로 롤백
+kubectl rollout history deployment/user-service -n kt-event-marketing
+kubectl rollout undo deployment/user-service --to-revision=2 -n kt-event-marketing
+```
+
+### 2. 이미지 태그로 롤백
+```bash
+# 특정 이미지 버전으로 변경
+kubectl set image deployment/user-service \
+  user-service=acrdigitalgarage01.azurecr.io/kt-event-marketing/user-service:{previous-sha} \
+  -n kt-event-marketing
+
+# 롤아웃 상태 확인
+kubectl rollout status deployment/user-service -n kt-event-marketing
+```
+
+---
+
+## 참고 자료
+
+- [GitHub Actions 공식 문서](https://docs.github.com/en/actions)
+- [Kustomize 공식 문서](https://kustomize.io/)
+- [Azure AKS 공식 문서](https://docs.microsoft.com/en-us/azure/aks/)
+- [Kubernetes 공식 문서](https://kubernetes.io/docs/)
+
+---
+
+## 변경 이력
+
+| 날짜 | 버전 | 변경 내용 | 작성자 |
+|------|------|-----------|--------|
+| 2025-10-29 | 1.0.0 | 초기 CI/CD 파이프라인 구축 | DevOps Team |
@@ -0,0 +1,288 @@
+# 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