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

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

개요

이 문서는 Phonebill 프로젝트의 Jenkins 기반 CI/CD 파이프라인 구축 및 운영 가이드입니다.

프로젝트 정보

항목	값
시스템명	phonebill
JDK 버전	21
Image Registry	docker.io
Image Organization	hiondal
K8s Context	minikube-remote
Namespace	phonebill

서비스 목록

• api-gateway (포트: 8080)
• user-service (포트: 8081)
• bill-service (포트: 8082)
• product-service (포트: 8083)
• kos-mock (포트: 8084)

---

1. 사전 준비사항

1.1 Jenkins 필수 플러그인

- Kubernetes
- Pipeline Utility Steps
- Docker Pipeline
- GitHub
- SonarQube Scanner

1.2 Jenkins Credentials 등록

Jenkins 관리 > Credentials > Add Credentials에서 등록:

Docker Hub Credentials

- Kind: Username with password
- ID: dockerhub-credentials
- Username: {DOCKERHUB_USERNAME}
- Password: {DOCKERHUB_PASSWORD}

SonarQube Token (선택사항)

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

1.3 SonarQube 설정 (선택사항)

Jenkins 관리 > Configure System > SonarQube servers:

- Name: SonarQube
- Server URL: http://{SONARQUBE_URL}
- Server authentication token: sonarqube-token (위에서 등록한 credential)

---

2. Kustomize 구조

2.1 디렉토리 구조

deployment/cicd/
├── Jenkinsfile
├── config/
│   ├── deploy_env_vars_dev
│   ├── deploy_env_vars_staging
│   └── deploy_env_vars_prod
├── scripts/
│   ├── deploy.sh
│   └── validate-resources.sh
└── kustomize/
    ├── base/
    │   ├── kustomization.yaml
    │   ├── common/
    │   │   ├── cm-common.yaml
    │   │   ├── secret-common.yaml
    │   │   └── ingress.yaml
    │   ├── api-gateway/
    │   ├── user-service/
    │   ├── bill-service/
    │   ├── product-service/
    │   └── kos-mock/
    └── overlays/
        ├── dev/
        ├── staging/
        └── prod/

2.2 환경별 설정 차이

항목	dev	staging	prod
Namespace	phonebill	phonebill-staging	phonebill-prod
Replicas	1	2	3
CPU Requests	256m	512m	1024m
Memory Requests	256Mi	512Mi	1024Mi
CPU Limits	1024m	2048m	4096m
Memory Limits	1024Mi	2048Mi	4096Mi
DDL_AUTO	update	validate	validate
SHOW_SQL	true	false	false
SSL Redirect	false	true	true

---

3. Jenkins Pipeline Job 생성

3.1 New Item > Pipeline 선택

3.2 Pipeline 설정

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

3.3 Pipeline Parameters 설정

파라미터	타입	기본값	설명
ENVIRONMENT	Choice	dev	배포 환경 (dev/staging/prod)
SKIP_SONARQUBE	String	true	SonarQube 분석 건너뛰기 (true/false)

---

4. 파이프라인 스테이지

4.1 Get Source

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

4.2 Setup Kubernetes

• Kubernetes 컨텍스트 설정
• 네임스페이스 생성

4.3 Build

• Gradle을 사용한 빌드 (테스트 제외)
• ./gradlew build -x test

4.4 SonarQube Analysis & Quality Gate (선택사항)

• SKIP_SONARQUBE=false일 때만 실행
• 각 서비스별 테스트 및 코드 품질 분석
• Quality Gate 통과 확인

4.5 Build & Push Images

• Podman을 사용한 컨테이너 이미지 빌드
• Docker Hub로 이미지 푸시
• 이미지 태그: {환경}-{타임스탬프}

4.6 Update Kustomize & Deploy

• Kustomize를 사용한 이미지 태그 업데이트
• Kubernetes 매니페스트 적용
• 배포 상태 확인

---

5. 배포 실행

5.1 Jenkins 파이프라인 실행

1. Jenkins > phonebill > Build with Parameters
2. ENVIRONMENT 선택 (dev/staging/prod)
3. SKIP_SONARQUBE 입력 (true 또는 false)
4. Build 클릭

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

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

# staging 환경 배포
./deployment/cicd/scripts/deploy.sh staging v1.0.0

# prod 환경 배포
./deployment/cicd/scripts/deploy.sh prod v1.0.0

5.3 배포 상태 확인

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

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

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

# 특정 Pod 로그 확인
kubectl logs -f deployment/api-gateway -n phonebill

---

6. 롤백

6.1 이전 버전으로 롤백

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

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

# 롤백 히스토리 확인
kubectl rollout history deployment/{서비스명} -n phonebill

6.2 이미지 태그 기반 롤백

cd deployment/cicd/kustomize/overlays/{환경}

# 이전 안정 버전 이미지 태그로 업데이트
kustomize edit set image docker.io/hiondal/{서비스명}:{환경}-{이전태그}

# 배포
kubectl apply -k .

---

7. 리소스 검증

7.1 검증 스크립트 실행

./deployment/cicd/scripts/validate-resources.sh

7.2 Kustomize 빌드 테스트

# 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/

---

8. SonarQube 설정 (선택사항)

8.1 Quality Gate 권장 설정

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

8.2 SonarQube 프로젝트 생성

각 서비스별로 다음 형식의 프로젝트 키로 생성:

• phonebill-user-service-dev
• phonebill-user-service-staging
• phonebill-user-service-prod

---

9. 트러블슈팅

9.1 이미지 푸시 실패

• Docker Hub 인증 정보 확인
• Rate Limit 확인 (무료 계정 제한)

9.2 배포 실패

# Pod 이벤트 확인
kubectl describe pod {POD_NAME} -n phonebill

# Pod 로그 확인
kubectl logs {POD_NAME} -n phonebill

9.3 Kustomize 빌드 실패

• 리소스 파일 존재 여부 확인
• YAML 문법 검증
• kubectl kustomize 명령으로 디버깅

9.4 SonarQube 연결 실패

• SonarQube 서버 URL 확인
• 인증 토큰 유효성 확인
• 네트워크 연결 확인

---

10. 체크리스트

사전 준비

• Jenkins 필수 플러그인 설치 완료
• Docker Hub Credentials 등록 완료
• SonarQube Token 등록 완료 (선택)
• Kubernetes 컨텍스트 설정 완료

배포 전

• 리소스 검증 스크립트 실행 완료
• 환경별 설정 파일 확인 완료
• Kustomize 빌드 테스트 완료

배포 후

• Pod 상태 확인 (Running)
• 서비스 엔드포인트 확인
• Ingress 접근 테스트
• 로그 이상 여부 확인