From 6e060089f9b5a9ca54848d4fe479a10b9d936e5b Mon Sep 17 00:00:00 2001 From: hiondal Date: Mon, 15 Sep 2025 09:52:53 +0900 Subject: [PATCH] =?UTF-8?q?GitHub=20Actions=20CI/CD=20=EC=A0=84=ED=99=98?= =?UTF-8?q?=20=EC=9E=91=EC=97=85=EA=B3=84=ED=9A=8D=EC=84=9C=20=EC=9E=91?= =?UTF-8?q?=EC=84=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Jenkins 파이프라인 분석 완료 - GitHub Actions 전환 계획 수립 - 8-12일 일정으로 단계적 전환 방안 제시 - 5개 마이크로서비스 병렬 처리 지원 - Azure 인프라 연동 방안 포함 - 위험 요소 및 대응 방안 정리 --- claude/github-actions-migration-plan.md | 308 ++++++++++++++++++++++++ 1 file changed, 308 insertions(+) create mode 100644 claude/github-actions-migration-plan.md diff --git a/claude/github-actions-migration-plan.md b/claude/github-actions-migration-plan.md new file mode 100644 index 0000000..81020eb --- /dev/null +++ b/claude/github-actions-migration-plan.md @@ -0,0 +1,308 @@ +# GitHub Actions CI/CD 전환 작업계획서 + +## 📋 개요 + +현재 Jenkins 기반 CI/CD 파이프라인을 GitHub Actions로 전환하여 더 효율적이고 관리하기 쉬운 DevOps 환경을 구축하는 작업계획서입니다. + +## 🎯 전환 목표 + +- **통합 개발 환경**: GitHub과 CI/CD의 완전한 통합 +- **관리 효율성**: Jenkins 인프라 관리 부담 제거 +- **보안 강화**: GitHub Secrets를 통한 안전한 자격증명 관리 +- **개발자 경험**: GitHub 인터페이스와 통합된 워크플로우 +- **비용 최적화**: 자체 관리형 Jenkins 인프라 비용 절감 + +## 🔍 현재 Jenkins CI/CD 분석 + +### 기존 Jenkins 파이프라인 구조 + +``` +Jenkins Pipeline +├── Pod Template (Kubernetes 기반) +│ ├── podman container (이미지 빌드) +│ ├── gradle container (빌드 & 테스트) +│ └── azure-cli container (배포) +├── 5개 서비스 병렬 처리 +│ ├── api-gateway +│ ├── user-service +│ ├── bill-service +│ ├── product-service +│ └── kos-mock +└── Kustomize 기반 쿠버네티스 배포 +``` + +### 현재 파이프라인 단계 +1. **Get Source**: SCM checkout +2. **Setup AKS**: Azure 인증 및 쿠버네티스 클러스터 연결 +3. **Build**: Gradle 빌드 (테스트 제외) +4. **SonarQube Analysis**: 코드 품질 분석 (선택적) +5. **Build & Push Images**: Podman으로 컨테이너 이미지 빌드/푸시 +6. **Update Kustomize & Deploy**: 쿠버네티스 배포 + +### 사용 중인 도구 및 서비스 +- **빌드 도구**: Gradle with JDK 21 +- **컨테이너**: Podman (Docker 대신 사용) +- **레지스트리**: Azure Container Registry (ACR) +- **배포**: Kustomize + kubectl +- **코드 품질**: SonarQube +- **인프라**: Azure Kubernetes Service (AKS) + +## 📊 전환 범위 및 우선순위 + +### 1단계: 핵심 워크플로우 구축 (필수) +- [ ] **기본 빌드 워크플로우**: Gradle 빌드 자동화 +- [ ] **컨테이너 이미지 빌드**: Docker 기반 이미지 빌드/푸시 +- [ ] **환경별 배포**: dev/staging/prod 환경 지원 +- [ ] **시크릿 관리**: 자격증명 및 환경변수 관리 + +### 2단계: 고도화 기능 (중요) +- [ ] **코드 품질 분석**: SonarQube 통합 +- [ ] **테스트 자동화**: 단위/통합 테스트 실행 +- [ ] **병렬 처리**: 5개 서비스 동시 빌드/배포 +- [ ] **배포 검증**: Health check 및 rollback 기능 + +### 3단계: 최적화 및 확장 (선택) +- [ ] **캐싱 전략**: 빌드 속도 최적화 +- [ ] **매트릭스 빌드**: 다중 환경/버전 지원 +- [ ] **알림 시스템**: 빌드 상태 알림 +- [ ] **보안 스캔**: 컨테이너 취약점 검사 + +## 🗂️ 파일 구조 계획 + +``` +.github/ +└── workflows/ + ├── ci-cd.yml # 메인 CI/CD 워크플로우 + ├── build-and-test.yml # 빌드 및 테스트만 실행 + ├── deploy-dev.yml # 개발환경 배포 + ├── deploy-staging.yml # 스테이징환경 배포 + └── deploy-prod.yml # 운영환경 배포 + +scripts/ +├── build-images.sh # 이미지 빌드 스크립트 +├── deploy-services.sh # 서비스 배포 스크립트 +└── health-check.sh # 배포 검증 스크립트 +``` + +## 🔧 기술 스택 매핑 + +### Jenkins → GitHub Actions 매핑 + +| Jenkins 요소 | GitHub Actions 대체 | 비고 | +|---------------|-------------------|------| +| Jenkinsfile | .github/workflows/*.yml | YAML 기반 워크플로우 | +| Pod Template | Ubuntu/Windows runners | GitHub hosted runners | +| Podman container | Docker/build-push-action | Docker 기반 이미지 빌드 | +| Gradle container | actions/setup-java | Java 21 + Gradle wrapper | +| Azure CLI container | azure/login | Azure 서비스 연결 | +| Credentials | GitHub Secrets | 암호화된 환경변수 | +| SonarQube | sonarqube-github-action | 코드 품질 분석 | + +### 환경변수 및 시크릿 + +**GitHub Secrets 필요 항목:** +``` +AZURE_CLIENT_ID +AZURE_CLIENT_SECRET +AZURE_TENANT_ID +ACR_USERNAME +ACR_PASSWORD +DOCKERHUB_USERNAME +DOCKERHUB_PASSWORD +SONARQUBE_TOKEN +SONARQUBE_HOST_URL +RESOURCE_GROUP_DEV +RESOURCE_GROUP_STAGING +RESOURCE_GROUP_PROD +CLUSTER_NAME_DEV +CLUSTER_NAME_STAGING +CLUSTER_NAME_PROD +``` + +## 📝 상세 작업 단계 + +### Phase 1: 환경 준비 (1-2일) + +#### 1.1 GitHub Repository 설정 +- [ ] GitHub Actions 활성화 확인 +- [ ] Branch protection rules 설정 +- [ ] Required status checks 구성 + +#### 1.2 시크릿 구성 +- [ ] Azure 서비스 주체 정보 등록 +- [ ] ACR 자격증명 등록 +- [ ] SonarQube 토큰 등록 +- [ ] 환경별 클러스터 정보 등록 + +#### 1.3 권한 설정 +- [ ] GitHub Actions service account 생성 +- [ ] AKS 클러스터 접근 권한 부여 +- [ ] ACR 이미지 푸시 권한 확인 + +### Phase 2: 기본 워크플로우 구축 (3-4일) + +#### 2.1 빌드 워크플로우 (.github/workflows/build.yml) +```yaml +# 예시 구조 +name: Build and Test +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main ] + +jobs: + build: + runs-on: ubuntu-latest + strategy: + matrix: + service: [api-gateway, user-service, bill-service, product-service, kos-mock] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-java@v4 + with: + java-version: '21' + distribution: 'temurin' + - name: Build with Gradle + run: ./gradlew :${{ matrix.service }}:build -x test +``` + +#### 2.2 이미지 빌드 워크플로우 +- [ ] Docker 기반 이미지 빌드 +- [ ] Multi-stage build 최적화 +- [ ] ACR 푸시 자동화 +- [ ] 이미지 태그 전략 수립 + +#### 2.3 배포 워크플로우 +- [ ] Kustomize 이미지 태그 업데이트 +- [ ] kubectl 배포 실행 +- [ ] 배포 상태 확인 +- [ ] Rollback 메커니즘 + +### Phase 3: 고도화 기능 (2-3일) + +#### 3.1 테스트 통합 +- [ ] 단위 테스트 실행 +- [ ] 통합 테스트 실행 +- [ ] 테스트 결과 리포팅 +- [ ] 커버리지 측정 + +#### 3.2 코드 품질 분석 +- [ ] SonarQube 분석 통합 +- [ ] Quality Gate 적용 +- [ ] PR 댓글로 품질 리포트 +- [ ] 실패 시 배포 중단 + +#### 3.3 병렬 처리 최적화 +- [ ] Matrix strategy 활용 +- [ ] Job dependencies 설정 +- [ ] 빌드 시간 최적화 +- [ ] 캐싱 전략 적용 + +### Phase 4: 검증 및 안정화 (2-3일) + +#### 4.1 기능 검증 +- [ ] 전체 파이프라인 End-to-End 테스트 +- [ ] 각 환경별 배포 검증 +- [ ] 롤백 기능 테스트 +- [ ] 성능 벤치마크 비교 + +#### 4.2 문서화 +- [ ] 워크플로우 사용법 문서 +- [ ] 트러블슈팅 가이드 +- [ ] 마이그레이션 체크리스트 +- [ ] 운영 매뉴얼 작성 + +## ⚠️ 위험 요소 및 대응 방안 + +### 기술적 위험 +| 위험 요소 | 영향도 | 대응 방안 | +|-----------|--------|----------| +| Podman → Docker 변환 | 중 | Docker 호환성 테스트, 이미지 빌드 검증 | +| Jenkins 종속성 | 높음 | 단계적 전환, 병렬 운영 기간 확보 | +| 환경별 설정 차이 | 중 | 환경별 상세 테스트, 설정 검증 도구 | +| 성능 차이 | 낮음 | 빌드 시간 벤치마크, 캐싱 최적화 | + +### 운영적 위험 +| 위험 요소 | 영향도 | 대응 방안 | +|-----------|--------|----------| +| 배포 중단 | 높음 | Blue-Green 배포, 즉시 롤백 가능 | +| 학습 곡선 | 중 | 교육 계획, 문서화 강화 | +| 권한 관리 복잡성 | 중 | IAM 정책 표준화, 최소 권한 원칙 | + +## 📊 성공 지표 + +### 기술적 지표 +- [ ] **빌드 시간**: 현재 대비 20% 이내 유지 +- [ ] **배포 성공률**: 99% 이상 +- [ ] **MTTR**: 평균 복구 시간 10분 이내 +- [ ] **파이프라인 가용성**: 99.9% 이상 + +### 운영적 지표 +- [ ] **관리 복잡성**: Jenkins 인프라 관리 불필요 +- [ ] **개발자 만족도**: GitHub 통합 워크플로우 +- [ ] **보안 개선**: 중앙화된 시크릿 관리 +- [ ] **비용 절감**: Jenkins 인프라 비용 제거 + +## 🗓️ 일정 계획 + +### 전체 일정: 8-12 일 +``` +Week 1 (Day 1-4): 환경 준비 + 기본 워크플로우 +├── Day 1-2: GitHub 설정, 시크릿 구성 +└── Day 3-4: 빌드 워크플로우 구축 + +Week 2 (Day 5-8): 고도화 + 검증 +├── Day 5-6: 이미지 빌드, 배포 워크플로우 +├── Day 7-8: 테스트, 품질 분석 통합 + +Week 3 (Day 9-12): 최적화 + 안정화 +├── Day 9-10: 병렬 처리, 성능 최적화 +└── Day 11-12: 검증, 문서화, 운영 전환 +``` + +### 마일스톤 +- **M1** (Day 4): 기본 빌드 파이프라인 완료 +- **M2** (Day 8): 전체 CI/CD 파이프라인 완료 +- **M3** (Day 12): 운영 환경 전환 완료 + +## ✅ 체크리스트 + +### 전환 전 준비사항 +- [ ] 현재 Jenkins 파이프라인 백업 +- [ ] GitHub Actions 사용량 한도 확인 +- [ ] 팀 구성원 GitHub Actions 교육 +- [ ] 롤백 계획 수립 + +### 전환 후 검증사항 +- [ ] 전체 서비스 빌드/배포 테스트 +- [ ] 환경별 배포 검증 +- [ ] 성능 벤치마크 비교 +- [ ] 보안 설정 점검 +- [ ] 문서화 완료 확인 + +## 📞 담당자 및 역할 + +### 핵심 담당자 +- **DevOps 리드**: 최운영/데옵스 - 워크플로우 설계, 인프라 연동 +- **Backend 리드**: 이개발/백엔더 - 빌드 스크립트, 테스트 통합 +- **QA 리드**: 정테스트/QA매니저 - 배포 검증, 품질 게이트 + +### 지원 역할 +- **Product Owner**: 김기획/기획자 - 일정 조율, 우선순위 결정 +- **Frontend Dev**: 박화면/프론트 - 프론트엔드 빌드 프로세스 + +## 💡 추천사항 + +1. **점진적 전환**: 개발환경부터 단계적으로 전환 +2. **병렬 운영**: 초기 안정화까지 Jenkins와 병행 운영 +3. **모니터링 강화**: 전환 후 집중 모니터링 기간 운영 +4. **피드백 수집**: 개발팀 피드백 기반 지속 개선 +5. **문서화 우선**: 모든 변경사항 실시간 문서화 + +--- + +**작성일**: 2025-01-14 +**작성자**: 최운영/데옵스 +**검토자**: 김기획/기획자, 이개발/백엔더 +**승인자**: Project Owner \ No newline at end of file