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

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

📋 개요

이 가이드는 통신요금 관리 서비스(phonebill)를 위한 Jenkins 기반 CI/CD 파이프라인 구축 방법을 안내합니다.

주요 특징:

• Jenkins + Kustomize 기반 CI/CD 파이프라인
• 환경별(dev/staging/prod) 매니페스트 관리
• SonarQube 코드 품질 분석과 Quality Gate
• Azure Container Registry(ACR) 연동
• AKS(Azure Kubernetes Service) 자동 배포

🏗 아키텍처 구성

Jenkins Pipeline
    ↓
┌─── Build & Test (Gradle) ─────┐
│   - 소스코드 빌드               │
│   - 단위 테스트 실행            │
│   - SonarQube 품질 분석        │
│   - Quality Gate 검증          │
└─────────────────────────────┘
    ↓
┌─── Container Build ───────────┐
│   - 서비스별 이미지 빌드        │
│   - ACR에 이미지 푸시          │
│   - 환경별 태그 관리           │
└─────────────────────────────┘
    ↓
┌─── Deploy to AKS ─────────────┐
│   - Kustomize 매니페스트 적용  │
│   - 환경별 설정 적용           │
│   - 배포 상태 확인             │
└─────────────────────────────┘

🛠 사전 준비사항

실행 환경 정보

• ACR명: acrdigitalgarage01
• 리소스 그룹: rg-digitalgarage-01
• AKS 클러스터: aks-digitalgarage-01

서비스 구성

• 시스템명: phonebill
• 서비스목록:
  • api-gateway
  • user-service
  • bill-service
  • product-service
  • kos-mock

🔧 Jenkins 환경 구성

1. Jenkins 필수 플러그인 설치

# Jenkins 관리 > 플러그인 관리에서 다음 플러그인 설치
- Kubernetes
- Pipeline Utility Steps
- Docker Pipeline
- GitHub
- SonarQube Scanner
- Azure Credentials

2. Jenkins Credentials 등록

Azure Service Principal 등록:

Manage Jenkins > Credentials > Add Credentials
- 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패스워드}

SonarQube Token 등록:

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

📂 Kustomize 구조

프로젝트에 다음과 같은 Kustomize 구조가 생성되었습니다:

deployment/cicd/
├── kustomize/
│   ├── base/
│   │   ├── kustomization.yaml
│   │   ├── namespace.yaml
│   │   ├── common/
│   │   │   ├── cm-common.yaml
│   │   │   ├── secret-common.yaml
│   │   │   ├── secret-imagepull.yaml
│   │   │   └── ingress.yaml
│   │   └── [각 서비스별 매니페스트]
│   └── overlays/
│       ├── dev/
│       ├── staging/
│       └── prod/
├── config/
│   ├── deploy_env_vars_dev
│   ├── deploy_env_vars_staging
│   └── deploy_env_vars_prod
├── scripts/
│   └── deploy.sh
└── Jenkinsfile

🚀 Jenkins Pipeline 설정

1. Pipeline Job 생성

1. Jenkins 웹 UI에서 New Item > Pipeline 선택

2. Pipeline script from SCM 설정:

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

3. Pipeline Parameters 설정:

   ENVIRONMENT: Choice Parameter (dev, staging, prod)
   IMAGE_TAG: String Parameter (default: latest)
   

2. Pipeline 단계별 설명

Stage 1: Get Source

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

Stage 2: Setup AKS

• Azure 서비스 프린시팔로 로그인
• AKS 클러스터 연결 설정
• 네임스페이스 생성

Stage 3: Build & SonarQube Analysis

• Gradle 빌드 및 테스트 실행
• 각 서비스별 SonarQube 분석
• 코드 커버리지 리포트 생성

Stage 4: Quality Gate

• SonarQube Quality Gate 결과 대기
• 품질 기준 미달 시 파이프라인 중단

Stage 5: Build & Push Images

• 서비스별 컨테이너 이미지 빌드
• ACR에 이미지 푸시
• 환경별 태그 적용

Stage 6: Update Kustomize & Deploy

• 이미지 태그 업데이트
• Kustomize를 통한 매니페스트 적용
• 배포 완료 대기

⚙ SonarQube 설정

Quality Gate 규칙

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

프로젝트별 분석 제외 항목

**/config/**
**/entity/**
**/dto/**
**/*Application.class
**/exception/**

🎯 배포 실행 방법

1. Jenkins 파이프라인 실행

1. Jenkins > {프로젝트명} > Build with Parameters
2. ENVIRONMENT 선택 (dev/staging/prod)
3. IMAGE_TAG 입력 (선택사항)
4. Build 클릭

2. 수동 배포 스크립트 실행

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

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

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

3. 배포 상태 확인

# Pod 상태 확인
kubectl get pods -n phonebill-{환경}

# 서비스 상태 확인
kubectl get services -n phonebill-{환경}

# Ingress 상태 확인
kubectl get ingress -n phonebill-{환경}

🔄 롤백 방법

1. Kubernetes 롤백

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

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

2. 이미지 태그 기반 롤백

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

🏷 환경별 설정 차이점

DEV 환경

• Replicas: 1개
• Resources: requests(256m/256Mi), limits(1024m/1024Mi)
• Domain: phonebill-api.20.214.196.128.nip.io
• SSL: 비활성화
• DDL: update

STAGING 환경

• Replicas: 2개
• Resources: requests(512m/512Mi), limits(2048m/2048Mi)
• Domain: phonebill-staging.example.com
• SSL: 활성화 (Let's Encrypt)
• DDL: validate

PROD 환경

• Replicas: 3개
• Resources: requests(1024m/1024Mi), limits(4096m/4096Mi)
• Domain: phonebill-prod.example.com
• SSL: 활성화 (Let's Encrypt)
• DDL: validate
• JWT: 보안 강화 (짧은 유효시간)

📋 체크리스트

사전 준비

• settings.gradle에서 시스템명과 서비스명 확인
• Azure 환경 정보 확인 (ACR, 리소스 그룹, AKS 클러스터)
• Jenkins 플러그인 설치 완료
• Jenkins Credentials 등록 완료

Kustomize 구성

• Base 매니페스트 복사 및 설정 완료
• 환경별 Overlay 구성 완료
• Patch 파일 작성 완료 (replicas, resources 포함)
• 환경별 설정 파일 생성 완료

Jenkins Pipeline

• Jenkinsfile 작성 완료
• Pipeline Job 생성 및 설정 완료
• SonarQube 연동 설정 완료
• 배포 스크립트 생성 및 권한 설정 완료

배포 테스트

• DEV 환경 배포 테스트 완료
• STAGING 환경 배포 테스트 완료
• PROD 환경 배포 테스트 완료
• 롤백 테스트 완료

🚨 트러블슈팅

일반적인 문제들

1. Quality Gate 실패

# 해결방법: SonarQube 분석 결과 확인 및 코드 개선
./gradlew sonar

2. 이미지 빌드 실패

# 해결방법: Dockerfile 및 빌드 컨텍스트 확인
podman build --no-cache -f deployment/container/Dockerfile-backend .

3. 배포 타임아웃

# 해결방법: 리소스 사용량 및 노드 상태 확인
kubectl describe pods -n phonebill-{환경}
kubectl top nodes

4. 네임스페이스 관련 오류

# 해결방법: 네임스페이스 수동 생성
kubectl create namespace phonebill-{환경}

📞 지원 및 문의

Jenkins CI/CD 파이프라인 운영 중 문제가 발생하면 다음을 확인해 주세요:

1. Jenkins 빌드 로그 확인
2. SonarQube Quality Gate 결과 확인
3. Kubernetes 클러스터 상태 확인
4. Azure Container Registry 연결 상태 확인

---

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

이제 각 환경별로 자동화된 빌드, 테스트, 배포가 가능합니다. SonarQube를 통한 코드 품질 관리와 Kustomize를 통한 환경별 설정 관리로 안정적인 DevOps 환경을 구축했습니다.