phonebill/.github/deploy-actions-cicd-back.md

백엔드 GitHub Actions 파이프라인 구축 가이드

📋 프로젝트 정보

시스템명: phonebill 서비스 목록: api-gateway, user-service, bill-service, product-service, kos-mock JDK 버전: 21 실행 환경:

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

🚀 GitHub Repository 환경 구성

Repository Secrets 설정

Repository Settings > Secrets and variables > Actions > Repository secrets에 등록:

# Azure Service Principal
AZURE_CREDENTIALS:
{
  "clientId": "{클라이언트ID}",
  "clientSecret": "{클라이언트시크릿}",
  "subscriptionId": "{구독ID}",
  "tenantId": "{테넌트ID}"
}

# ACR Credentials
ACR_USERNAME: acrdigitalgarage01
ACR_PASSWORD: {ACR패스워드}

# SonarQube (선택사항)
SONAR_TOKEN: {SonarQube토큰}
SONAR_HOST_URL: {SonarQube서버URL}

# Docker Hub (Rate Limit 해결용, 선택사항)
DOCKERHUB_USERNAME: {Docker Hub 사용자명}
DOCKERHUB_PASSWORD: {Docker Hub 패스워드}

Repository Variables 설정

Repository Settings > Secrets and variables > Actions > Variables > Repository variables에 등록:

# Workflow 제어 변수
ENVIRONMENT: dev (기본값, 수동실행시 선택 가능: dev/staging/prod)
SKIP_SONARQUBE: true (기본값, 수동실행시 선택 가능: true/false)

사용 방법

• 자동 실행: Push/PR 시 기본값 사용 (ENVIRONMENT=dev, SKIP_SONARQUBE=true)
• 수동 실행: Actions 탭 > "Backend Services CI/CD" > "Run workflow" 버튼 클릭
  • Environment: dev/staging/prod 선택
  • Skip SonarQube Analysis: true/false 선택

📁 디렉토리 구조

.github/
├── kustomize/                    # GitHub Actions 전용 Kustomize 매니페스트
│   ├── base/                     # 기본 매니페스트
│   │   ├── kustomization.yaml
│   │   ├── namespace.yaml
│   │   ├── common/               # 공통 리소스
│   │   │   ├── cm-common.yaml
│   │   │   ├── secret-common.yaml
│   │   │   ├── secret-imagepull.yaml
│   │   │   └── ingress.yaml
│   │   ├── api-gateway/          # API Gateway 리소스
│   │   ├── user-service/         # User Service 리소스
│   │   ├── bill-service/         # Bill Service 리소스
│   │   ├── product-service/      # Product Service 리소스
│   │   └── kos-mock/             # KOS Mock 리소스
│   └── overlays/                 # 환경별 오버레이
│       ├── dev/                  # 개발 환경
│       ├── staging/              # 스테이징 환경
│       └── prod/                 # 운영 환경
├── config/                       # 환경별 배포 설정
│   ├── deploy_env_vars_dev
│   ├── deploy_env_vars_staging
│   └── deploy_env_vars_prod
├── scripts/                      # 배포 스크립트
│   └── deploy-actions.sh
└── workflows/                    # GitHub Actions 워크플로우
    └── backend-cicd.yaml

🔄 환경별 설정

DEV 환경

• 네임스페이스: phonebill-dev
• 프로파일: dev
• DDL 모드: update
• 리플리카: 1개
• 리소스: 256Mi/256m (요청), 1024Mi/1024m (제한)
• 도메인: phonebill-api.20.214.196.128.nip.io (기존과 동일)
• HTTPS: 비활성화

STAGING 환경

• 네임스페이스: phonebill-staging
• 프로파일: staging
• DDL 모드: validate
• 리플리카: 2개
• 리소스: 512Mi/512m (요청), 2048Mi/2048m (제한)
• 도메인: phonebill.staging.example.com
• HTTPS: 활성화 (ssl-redirect: true)

PROD 환경

• 네임스페이스: phonebill-prod
• 프로파일: prod
• DDL 모드: validate
• 리플리카: 3개
• 리소스: 1024Mi/1024m (요청), 4096Mi/4096m (제한)
• 도메인: phonebill.example.com
• HTTPS: 활성화 (ssl-redirect: true)
• JWT 토큰: 보안 강화 (ACCESS: 1시간, REFRESH: 12시간)

🚀 배포 방법

1. 자동 배포 (GitHub Actions)

코드 Push 시 자동 실행:

git add .
git commit -m "feature: 새 기능 추가"
git push origin main  # 또는 develop

수동 트리거:

1. GitHub > Actions 탭 이동
2. "Backend Services CI/CD" 선택
3. "Run workflow" 클릭
4. 환경(dev/staging/prod) 및 SonarQube 분석 여부 선택
5. "Run workflow" 실행

2. 수동 배포 (로컬)

# 개발 환경 배포
./.github/scripts/deploy-actions.sh dev latest

# 스테이징 환경 배포
./.github/scripts/deploy-actions.sh staging 20241215120000

# 운영 환경 배포
./.github/scripts/deploy-actions.sh prod 20241215120000

🔙 롤백 방법

1. GitHub Actions 롤백

# 이전 성공한 워크플로우 실행으로 롤백
1. GitHub > Actions > 성공한 이전 워크플로우 선택
2. "Re-run all jobs" 클릭

2. kubectl 롤백

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

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

3. 수동 스크립트 롤백

# 이전 안정 버전 이미지 태그로 배포
./.github/scripts/deploy-actions.sh {환경} {이전태그}

📊 SonarQube 프로젝트 설정

각 서비스별 프로젝트 생성 및 Quality Gate 설정:

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

✅ 체크리스트

사전 준비

• GitHub Repository Secrets 설정 완료
• GitHub Repository Variables 설정 완료
• Azure Service Principal 권한 확인
• ACR 접근 권한 확인
• AKS 클러스터 접근 권한 확인

배포 확인

• GitHub Actions 워크플로우 정상 실행
• 모든 서비스 이미지 빌드 및 푸시 성공
• Kustomize 매니페스트 적용 성공
• 모든 Deployment 정상 배포 (Available 상태)
• Health Check 통과
• Ingress 정상 동작 확인

서비스 검증

• API Gateway 응답 확인: curl -f http://localhost:8080/actuator/health
• 각 서비스별 Pod 상태 확인: kubectl get pods -n phonebill-{환경}
• 서비스 연결 확인: kubectl get services -n phonebill-{환경}
• Ingress 설정 확인: kubectl get ingress -n phonebill-{환경}

🔧 문제 해결

일반적인 문제

1. 이미지 빌드 실패: Dockerfile 경로 및 빌드 컨텍스트 확인
2. 매니페스트 적용 실패: Kustomize 구문 오류 확인
3. Pod 시작 실패: 환경변수 및 Secret 설정 확인
4. Health Check 실패: 애플리케이션 로그 확인

로그 확인 명령어

# Pod 로그 확인
kubectl logs -n phonebill-{환경} {pod-name}

# Deployment 상태 확인
kubectl describe deployment -n phonebill-{환경} {deployment-name}

# 이벤트 확인
kubectl get events -n phonebill-{환경} --sort-by='.lastTimestamp'

---

📞 지원

구축 과정에서 문제가 발생하거나 추가 지원이 필요한 경우, 다음 사항을 포함하여 문의:

1. 환경 정보 (dev/staging/prod)
2. 오류 메시지 및 로그
3. 실행한 명령어
4. 현재 상태 (kubectl get all -n phonebill-{환경})

구축 완료 🎉