phonebill/deployment/cicd/jenkins-pipeline-guide.md

phonebill Jenkins CI/CD 파이프라인 구축 가이드

📋 개요

본 가이드는 phonebill 프로젝트를 위한 Jenkins + Kustomize 기반 CI/CD 파이프라인 구축 방법을 제공합니다.

프로젝트 정보

• 시스템명: phonebill
• 서비스 목록: api-gateway, user-service, bill-service, product-service, kos-mock
• JDK 버전: 21
• Azure 환경:
  • ACR: acrdigitalgarage01
  • 리소스 그룹: rg-digitalgarage-01
  • AKS 클러스터: aks-digitalgarage-01
  • 네임스페이스: phonebill-dg0500

🏗️ 파이프라인 아키텍처

주요 구성 요소

• 빌드: Gradle 기반 멀티모듈 빌드
• 품질 검증: SonarQube 분석 & Quality Gate
• 컨테이너화: Podman 기반 이미지 빌드
• 배포: Kustomize를 통한 환경별 배포
• 인프라: AKS (Azure Kubernetes Service)

환경별 설정

환경	Replicas	CPU Request	Memory Request	CPU Limit	Memory Limit
dev	1	256m	256Mi	1024m	1024Mi
staging	2	512m	512Mi	2048m	2048Mi
prod	3	1024m	1024Mi	4096m	4096Mi

🚀 Jenkins 서버 환경 구성

1. Jenkins 필수 플러그인 설치

Jenkins 관리 > Plugin Manager에서 다음 플러그인들을 설치해주세요:

# Jenkins 필수 플러그인 목록
- Kubernetes
- Pipeline Utility Steps
- Docker Pipeline
- GitHub
- SonarQube Scanner
- Azure Credentials

2. Jenkins Credentials 등록

Manage Jenkins > Credentials > Add Credentials에서 다음 인증 정보들을 등록해주세요:

Azure Service Principal

Kind: Microsoft Azure Service Principal
ID: azure-credentials
Subscription ID: {구독ID}
Client ID: {클라이언트ID}
Client Secret: {클라이언트시크릿}
Tenant ID: {테넌트ID}
Azure Environment: Azure

ACR Credentials

Kind: Username with password
ID: acr-credentials
Username: acrdigitalgarage01
Password: {ACR_PASSWORD}

Docker Hub Credentials (Rate Limit 해결용)

Kind: Username with password
ID: dockerhub-credentials
Username: {DOCKERHUB_USERNAME}
Password: {DOCKERHUB_PASSWORD}
참고: Docker Hub 무료 계정 생성 (https://hub.docker.com)

SonarQube Token

Kind: Secret text
ID: sonarqube-token
Secret: {SonarQube토큰}

📂 Kustomize 구조

deployment/cicd/kustomize/
├── base/
│   ├── kustomization.yaml          # Base 설정
│   ├── common/                     # 공통 리소스
│   │   ├── cm-common.yaml
│   │   ├── secret-common.yaml
│   │   ├── secret-imagepull.yaml
│   │   └── ingress.yaml
│   ├── api-gateway/                # API Gateway 리소스
│   │   ├── deployment.yaml
│   │   ├── service.yaml
│   │   └── cm-api-gateway.yaml
│   ├── user-service/               # User Service 리소스
│   │   ├── deployment.yaml
│   │   ├── service.yaml
│   │   ├── cm-user-service.yaml
│   │   └── secret-user-service.yaml
│   ├── bill-service/               # Bill Service 리소스
│   │   ├── deployment.yaml
│   │   ├── service.yaml
│   │   ├── cm-bill-service.yaml
│   │   └── secret-bill-service.yaml
│   ├── product-service/            # Product Service 리소스
│   │   ├── deployment.yaml
│   │   ├── service.yaml
│   │   ├── cm-product-service.yaml
│   │   └── secret-product-service.yaml
│   └── kos-mock/                   # KOS Mock 리소스
│       ├── deployment.yaml
│       ├── service.yaml
│       └── cm-kos-mock.yaml
└── overlays/
    ├── dev/                        # 개발 환경
    │   ├── kustomization.yaml
    │   ├── cm-common-patch.yaml
    │   ├── secret-common-patch.yaml
    │   ├── ingress-patch.yaml
    │   ├── deployment-*-patch.yaml (각 서비스별)
    │   └── secret-*-patch.yaml (Secret 보유 서비스)
    ├── staging/                    # 스테이징 환경
    │   └── (dev와 동일한 구조)
    └── prod/                       # 운영 환경
        └── (dev와 동일한 구조)

🔧 Jenkins Pipeline Job 생성

1. 새 Pipeline Job 생성

1. Jenkins 대시보드에서 New Item 클릭
2. Pipeline 선택하고 프로젝트명 입력
3. OK 클릭

2. Pipeline 설정

General 탭

• Build Parameters 추가:

  ENVIRONMENT: Choice Parameter
    Choices: dev, staging, prod
    Default: dev
  
  IMAGE_TAG: String Parameter
    Default: latest
    Description: 이미지 태그 (기본값: latest)
  
  SKIP_SONARQUBE: String Parameter
    Default: true
    Description: SonarQube 분석 건너뛰기 (true/false)
  

Pipeline 탭

Definition: Pipeline script from SCM
SCM: Git
Repository URL: {Git저장소URL}
Branch: main (또는 develop)
Script Path: deployment/cicd/Jenkinsfile

📊 SonarQube 프로젝트 설정

1. 각 서비스별 SonarQube 프로젝트 생성

• phonebill-api-gateway-{환경}
• phonebill-user-service-{환경}
• phonebill-bill-service-{환경}
• phonebill-product-service-{환경}
• phonebill-kos-mock-{환경}

2. Quality Gate 설정

Coverage: >= 80%
Duplicated Lines: <= 3%
Maintainability Rating: <= A
Reliability Rating: <= A
Security Rating: <= A

🚀 배포 실행 방법

1. Jenkins Pipeline 실행

1. Jenkins > {프로젝트명} > Build with Parameters 클릭
2. 파라미터 설정:
   • ENVIRONMENT: dev/staging/prod 선택
   • IMAGE_TAG: 이미지 태그 입력 (선택사항)
   • SKIP_SONARQUBE: SonarQube 분석 건너뛰려면 "true", 실행하려면 "false"
3. Build 클릭

2. 수동 배포 (스크립트 사용)

# 개발 환경 배포
./deployment/cicd/scripts/deploy.sh dev 20241230120000

# 스테이징 환경 배포
./deployment/cicd/scripts/deploy.sh staging 20241230120000

# 운영 환경 배포
./deployment/cicd/scripts/deploy.sh prod 20241230120000

3. 배포 상태 확인

# Pod 상태 확인
kubectl get pods -n phonebill-dg0500

# 서비스 상태 확인
kubectl get services -n phonebill-dg0500

# Ingress 상태 확인
kubectl get ingress -n phonebill-dg0500

# 특정 서비스 로그 확인
kubectl logs -f deployment/user-service -n phonebill-dg0500

🔍 리소스 검증

리소스 검증 스크립트 실행

# 모든 Kustomize 리소스 검증
./deployment/cicd/scripts/validate-resources.sh

수동 검증 명령어

# Base 검증
kubectl kustomize deployment/cicd/kustomize/base/

# 환경별 검증
kubectl kustomize deployment/cicd/kustomize/overlays/dev/
kubectl kustomize deployment/cicd/kustomize/overlays/staging/
kubectl kustomize deployment/cicd/kustomize/overlays/prod/

🔄 롤백 방법

1. Kubernetes 롤백

# 특정 버전으로 롤백
kubectl rollout undo deployment/{서비스명} -n phonebill-dg0500 --to-revision=2

# 롤백 상태 확인
kubectl rollout status deployment/{서비스명} -n phonebill-dg0500

2. 이미지 태그 기반 롤백

# 이전 안정 버전 이미지 태그로 업데이트
cd deployment/cicd/kustomize/overlays/{환경}
kustomize edit set image acrdigitalgarage01.azurecr.io/phonebill/{서비스명}:{환경}-{이전태그}
kubectl apply -k .

🎯 파이프라인 단계별 설명

1. Get Source

• Git 저장소에서 소스코드 체크아웃
• 환경별 설정 파일 로드

2. Setup AKS

• Azure CLI를 통한 AKS 클러스터 연결
• 네임스페이스 생성 (phonebill-dg0500)

3. Build

• Gradle을 통한 멀티모듈 빌드
• 테스트는 SonarQube 단계에서 실행

4. SonarQube Analysis & Quality Gate

• 각 서비스별 개별 테스트 실행
• JaCoCo 코드 커버리지 리포트 생성
• SonarQube 정적 분석
• Quality Gate 통과 검증

5. Build & Push Images

• Podman을 통한 컨테이너 이미지 빌드
• 환경별 태그로 ACR에 푸시
• 30분 타임아웃 설정

6. Update Kustomize & Deploy

• Kustomize를 통한 이미지 태그 업데이트
• 환경별 매니페스트 적용
• 배포 완료까지 대기 (5분 타임아웃)

7. Pipeline Complete

• 파이프라인 완료 상태 로깅
• Pod 자동 정리 (3초 후 종료)

⚠️ 주의사항

1. 파드 자동 정리

• 파이프라인 완료 시 에이전트 파드 자동 삭제
• podRetention: never() 설정으로 즉시 정리
• 리소스 절약을 위한 필수 설정

2. 변수 참조 문법

• Jenkins Groovy에서는 ${variable} 사용
• \${variable} 사용 시 "syntax error: bad substitution" 오류 발생

3. 쉘 호환성

• Jenkins 컨테이너 기본 쉘이 /bin/sh인 경우
• Bash 배열 문법 () 미지원으로 공백 구분 문자열 사용

4. 환경별 설정 차이점

• DEV: SSL 리다이렉트 비활성화, 기본 도메인 사용
• STAGING/PROD: SSL 리다이렉트 활성화, 사용자 정의 도메인, 인증서 설정

🛠️ 트러블슈팅

1. 빌드 실패

# Gradle 캐시 클리어
./gradlew clean build

# JDK 버전 확인
java -version

2. 이미지 푸시 실패

# ACR 로그인 확인
az acr login --name acrdigitalgarage01

# Docker Hub rate limit 확인
docker info | grep -i rate

3. 배포 실패

# 네임스페이스 확인
kubectl get namespaces

# 리소스 상태 확인
kubectl describe deployment/{서비스명} -n phonebill-dg0500

4. SonarQube 분석 실패

• SonarQube 서버 연결 상태 확인
• 토큰 유효성 검증
• Quality Gate 설정 확인

📈 모니터링 및 로그

1. Jenkins 빌드 히스토리

• 각 단계별 실행 시간 추적
• 실패 단계 및 원인 분석

2. 애플리케이션 로그

# 실시간 로그 모니터링
kubectl logs -f deployment/{서비스명} -n phonebill-dg0500

# 특정 기간 로그 확인
kubectl logs deployment/{서비스명} -n phonebill-dg0500 --since=1h

3. 성능 메트릭

• Kubernetes 메트릭 서버 활용
• 각 서비스별 리소스 사용량 모니터링

---

📞 지원

문의사항이나 문제 발생 시:

1. Jenkins 빌드 로그 확인
2. Kubernetes 이벤트 확인: kubectl get events -n phonebill-dg0500
3. 리소스 검증 스크립트 실행: ./deployment/cicd/scripts/validate-resources.sh

최운영/데옵스: phonebill Jenkins CI/CD 파이프라인이 성공적으로 구축되었습니다! 🎉