phonebill/.github/actions-pipeline-guide.md

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

개요

phonebill 시스템을 위한 GitHub Actions 기반 CI/CD 파이프라인이 성공적으로 구축되었습니다.

프로젝트 정보

• 시스템명: phonebill
• 서비스: api-gateway, user-service, bill-service, product-service, kos-mock
• JDK 버전: 21
• Azure 환경: ACR(acrdigitalgarage01), AKS(aks-digitalgarage-01), RG(rg-digitalgarage-01)
• 네임스페이스: phonebill-dg0500

구축된 파일 구조

.github/
├── kustomize/
│   ├── base/
│   │   ├── kustomization.yaml
│   │   ├── common/
│   │   │   ├── cm-common.yaml
│   │   │   ├── secret-common.yaml
│   │   │   ├── secret-imagepull.yaml
│   │   │   └── ingress.yaml
│   │   └── {서비스명}/
│   │       ├── deployment.yaml
│   │       ├── service.yaml
│   │       ├── cm-{서비스명}.yaml
│   │       └── secret-{서비스명}.yaml (해당되는 경우)
│   └── overlays/
│       ├── dev/
│       │   ├── kustomization.yaml
│       │   ├── cm-common-patch.yaml
│       │   ├── ingress-patch.yaml
│       │   ├── deployment-{서비스명}-patch.yaml
│       │   ├── secret-common-patch.yaml
│       │   └── secret-{서비스명}-patch.yaml
│       ├── staging/
│       │   └── (dev와 동일한 구조, staging 환경 설정)
│       └── prod/
│           └── (dev와 동일한 구조, prod 환경 설정)
├── config/
│   ├── deploy_env_vars_dev
│   ├── deploy_env_vars_staging
│   └── deploy_env_vars_prod
├── scripts/
│   └── deploy-actions.sh
└── workflows/
    └── backend-cicd.yaml

GitHub Repository 설정

1. Repository Secrets 설정

GitHub Repository → Settings → Secrets and variables → Actions → Repository secrets에 다음 설정:

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

# ACR Credentials (az acr credential show --name acrdigitalgarage01)
ACR_USERNAME: acrdigitalgarage01
ACR_PASSWORD: {ACR패스워드}

# SonarQube 설정
SONAR_HOST_URL: http://{External IP}  # k get svc -n sonarqube로 확인
SONAR_TOKEN: {SonarQube토큰}  # SonarQube > My Account > Security에서 생성

# Docker Hub (Rate Limit 방지)
DOCKERHUB_USERNAME: {Docker Hub 사용자명}
DOCKERHUB_PASSWORD: {Docker Hub 패스워드}

2. Repository Variables 설정

GitHub Repository → Settings → Secrets and variables → Actions → Variables → Repository variables에 다음 설정:

ENVIRONMENT: dev (기본값)
SKIP_SONARQUBE: true (기본값)

파이프라인 실행 방법

1. 자동 실행

• 트리거: main/develop 브랜치에 push 또는 main 브랜치에 PR
• 환경: dev (기본값)
• SonarQube: 스킵 (기본값)

2. 수동 실행

1. GitHub → Actions 탭 이동
2. "Backend Services CI/CD" 워크플로우 선택
3. "Run workflow" 버튼 클릭
4. 환경 선택 (dev/staging/prod)
5. SonarQube 분석 여부 선택 (true/false)

파이프라인 단계

1. Build and Test

• Gradle 빌드 (테스트 제외)
• SonarQube 코드 품질 분석 (선택사항)
• 빌드 아티팩트 업로드

2. Build and Push Docker Images

• 각 서비스별 Docker 이미지 빌드
• Azure Container Registry에 푸시
• 이미지 태그: {환경}-{타임스탬프}

3. Deploy to Kubernetes

• Kustomize를 사용한 환경별 매니페스트 생성
• AKS 클러스터에 배포
• 배포 상태 확인

환경별 설정

DEV 환경

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

STAGING 환경

• Replicas: 2
• Resources: requests(512Mi/512m), limits(2048Mi/2048m)
• DDL: validate
• SSL: 활성화
• Host: phonebill-staging.digitalgarage.com
• JWT: 운영 환경 토큰 유효시간

PROD 환경

• Replicas: 3
• Resources: requests(1024Mi/1024m), limits(4096Mi/4096m)
• DDL: validate
• SSL: 활성화
• Host: phonebill.digitalgarage.com
• JWT: 보안 강화된 짧은 토큰 유효시간

수동 배포 방법

로컬에서 수동 배포를 수행하려면:

# 기본 dev 환경으로 배포
./.github/scripts/deploy-actions.sh

# 특정 환경과 이미지 태그로 배포
./.github/scripts/deploy-actions.sh staging 20241001123000

# 권한 오류 시
chmod +x .github/scripts/deploy-actions.sh

롤백 방법

1. GitHub Actions를 통한 롤백

1. GitHub → Actions → 성공한 이전 워크플로우 선택
2. "Re-run all jobs" 클릭

2. kubectl을 이용한 롤백

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

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

3. 수동 스크립트를 이용한 롤백

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

SonarQube Quality Gate 설정

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

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

모니터링 및 확인

배포 상태 확인

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

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

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

# 로그 확인
kubectl logs -f deployment/{서비스명} -n phonebill-dg0500

헬스 체크

# API Gateway 헬스 체크
curl -f http://phonebill-dg0500-api.20.214.196.128.nip.io/actuator/health

주요 특징

1. 환경별 분리: dev, staging, prod 환경별 독립적인 설정
2. Kustomize 사용: 환경별 매니페스트 관리 자동화
3. SonarQube 통합: 코드 품질 분석 및 Quality Gate
4. Docker 최적화: Multi-stage 빌드 및 Rate Limit 방지
5. 자동 배포: Push/PR 시 자동 빌드 및 배포
6. 수동 배포: 운영진이 필요 시 수동 실행 가능
7. 롤백 지원: 다양한 방법의 롤백 기능

문제 해결

일반적인 오류

1. Azure 인증 실패

   • AZURE_CREDENTIALS 설정 확인
   • Service Principal 권한 확인

2. ACR 접근 실패

   • ACR_USERNAME, ACR_PASSWORD 확인
   • ACR 권한 설정 확인

3. SonarQube 분석 실패

   • SONAR_TOKEN, SONAR_HOST_URL 확인
   • SonarQube 서버 접근성 확인

4. Kustomize 오류

   • patch 파일 경로 및 target 확인
   • YAML 문법 오류 확인

연락처

문제 발생 시 DevOps 팀에 문의하거나 GitHub Issues를 통해 보고해 주세요.

---

최운영/데옵스: GitHub Actions CI/CD 파이프라인 구축이 완료되었습니다! 🎉