chpark/vexplor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a0209856302772df06d7eb54a00f097bc0e4e7cc
vexplor/DEPLOYMENT_GUIDE_KPSLP.md
dohyeons 873addb96a feat: 원본 최신 소스 반영 + NCP Kubernetes 배포 설정 추가 
- 원본 ERP-node 프로젝트의 최신 코드 반영
- NCP Kubernetes 배포를 위한 인프라 파일 추가
  - Jenkinsfile: Kaniko 기반 CI/CD 파이프라인
  - Dockerfile: 멀티스테이지 빌드 (백엔드 + 프론트엔드)
  - values_logistream.yaml: Helm 차트 values 파일
  - DEPLOYMENT_GUIDE_KPSLP.md: 배포 가이드 문서
- 불필요한 마이그레이션 계획 문서 36개 정리
2025-11-10 14:20:10 +09:00

7.8 KiB
Raw Blame History

vexplor 프로젝트 NCP Kubernetes 배포 가이드

배포 환경

  • Kubernetes 클러스터: NCP Kubernetes
  • 네임스페이스: apps
  • GitOps 도구: Argo CD (https://argocd.kpslp.kr)
  • CI/CD: Jenkins (Kaniko 빌드)
  • 컨테이너 레지스트리: registry.kpslp.kr

전제 조건

1. GitLab 레포지토리

  • 프로젝트 코드 레포: 이미 생성됨 (현재 레포)
  • Helm Charts 레포: https://gitlab.kpslp.kr/root/helm-charts 접근 권한 필요

2. 필요한 권한

  • GitLab 계정 및 레포지토리 접근 권한
  • Jenkins 프로젝트 생성 권한 또는 담당자 요청
  • Argo CD 접속 계정
  • Container Registry 푸시 권한

배포 단계

Step 1: Helm Charts 레포지토리 설정

김욱동 책임님께 다음 사항을 요청하세요:

안녕하세요.

vexplor 프로젝트 배포를 위해 다음 작업이 필요합니다:

1. helm-charts 레포지토리 접근 권한 부여
   - 레포지토리: https://gitlab.kpslp.kr/root/helm-charts
   - 현재 404 오류로 접근 불가
   - 계정: [본인 GitLab 사용자명]

2. values 파일 업로드
   - 첨부된 values_vexplor.yaml 파일을 
   - kpslp/values_vexplor.yaml 경로에 업로드해주시거나
   - 업로드 방법을 안내해주세요

3. Jenkins 프로젝트 생성
   - 프로젝트명: vexplor
   - Git 레포지토리: [현재 프로젝트 GitLab URL]
   - Jenkinsfile: 프로젝트 루트에 이미 준비됨

감사합니다.

첨부 파일: values_vexplor.yaml (프로젝트 루트에 생성됨)

Step 2: Jenkins 프로젝트 등록

Jenkins에서 새 파이프라인 프로젝트를 생성합니다:

  1. Jenkins 접속 (URL은 담당자에게 문의)
  2. New Item 클릭
  3. 프로젝트명: vexplor
  4. Pipeline 선택
  5. Pipeline 설정:
    • Definition: Pipeline script from SCM
    • SCM: Git
    • Repository URL: [현재 프로젝트 GitLab URL]
    • Credentials: gitlab_userpass_root (또는 담당자가 안내한 credential)
    • Branch: */main
    • Script Path: Jenkinsfile

Step 3: Argo CD 애플리케이션 등록

  1. Argo CD 접속: https://argocd.kpslp.kr

  2. New App 생성:

    • Application Name: vexplor
    • Project: default
    • Sync Policy: Automatic (자동 배포) 또는 Manual (수동 배포)
    • Auto-Create Namespace: ✓ (체크)

  3. Source 설정:

    • Repository URL: https://gitlab.kpslp.kr/root/helm-charts
    • Revision: HEAD 또는 main
    • Path: kpslp
    • Helm Values: values_vexplor.yaml

  4. Destination 설정:

    • Cluster URL: https://kubernetes.default.svc (기본값)
    • Namespace: apps

  5. Create 클릭

Step 4: 첫 배포 실행

4-1. Git Push로 Jenkins 빌드 트리거

git add .
git commit -m "feat: NCP Kubernetes 배포 설정 완료"
git push origin main

4-2. Jenkins 빌드 모니터링

  1. Jenkins에서 vexplor 프로젝트 열기
  2. 빌드 시작 확인 (자동 트리거 또는 수동 빌드)
  3. 로그 확인:
    • Checkout: Git 소스 다운로드
    • Build: Docker 이미지 빌드 (registry.kpslp.kr/slp/vexplor:xxxxx)
    • Update Image Tag: helm-charts 레포의 values 파일 업데이트

4-3. Argo CD 배포 확인

  1. Argo CD 대시보드에서 vexplor 앱 열기
  2. Sync Status: OutOfSync → Synced 변경 확인
  3. Health Status: Progressing → Healthy 변경 확인
  4. Pod 상태 확인 (Running 상태여야 함)

배포 후 확인사항

1. Pod 상태 확인

kubectl get pods -n apps | grep vexplor

예상 출력:

vexplor-xxxxxxxxxx-xxxxx   1/1     Running   0          2m

2. 서비스 확인

kubectl get svc -n apps | grep vexplor

3. Ingress 확인

kubectl get ingress -n apps | grep vexplor

4. 로그 확인

# 전체 로그
kubectl logs -n apps -l app=vexplor

# 최근 50줄
kubectl logs -n apps -l app=vexplor --tail=50

# 실시간 로그 (스트리밍)
kubectl logs -n apps -l app=vexplor -f

5. 애플리케이션 접속

  • URL: https://vexplor.kpslp.kr (values 파일에 설정한 도메인)
  • 헬스체크: https://vexplor.kpslp.kr/api/health

트러블슈팅

문제 1: Jenkins 빌드 실패

증상: Build 단계에서 에러 발생

확인사항:

  • Docker 이미지 빌드 로그 확인
  • Dockerfile이 프로젝트 루트에 있는지 확인
  • 빌드 컨텍스트에 필요한 파일들이 있는지 확인

해결:

# 로컬에서 Docker 빌드 테스트
docker build -f Dockerfile -t vexplor:test .

문제 2: helm-charts 레포 푸시 실패

증상: Update Image Tag 단계에서 실패

원인: gitlab_userpass_root credential 문제 또는 권한 부족

해결: 김욱동 책임님께 credential 확인 요청

문제 3: Argo CD Sync 실패

증상: OutOfSync 상태에서 변경 없음

확인사항:

  • values 파일이 올바른 경로에 있는지 (kpslp/values_vexplor.yaml)
  • Argo CD가 helm-charts 레포를 읽을 수 있는지

해결: Argo CD에서 수동 Sync 시도 또는 담당자에게 문의

문제 4: Pod가 CrashLoopBackOff 상태

증상: Pod가 계속 재시작됨

확인:

kubectl describe pod -n apps [pod-name]
kubectl logs -n apps [pod-name] --previous

일반적인 원인:

  • 환경 변수 누락 (DATABASE_HOST 등)
  • 데이터베이스 연결 실패
  • 포트 바인딩 문제

해결:

  1. values_vexplor.yaml의 env 섹션 확인
  2. 데이터베이스 서비스명 확인 (postgres-service.apps.svc.cluster.local)
  3. Secret 설정 확인 (DB 비밀번호 등)

업데이트 배포 프로세스

코드 수정 후 배포 절차:

# 1. 코드 수정
git add .
git commit -m "feat: 새로운 기능 추가"
git push origin main

# 2. Jenkins 자동 빌드 (자동 트리거)
# - Git push 감지
# - Docker 이미지 빌드
# - 새 이미지 태그로 values 파일 업데이트

# 3. Argo CD 자동 배포 (Sync Policy가 Automatic인 경우)
# - helm-charts 레포 변경 감지
# - Kubernetes에 새 이미지 배포
# - Rolling Update 수행

수동 배포: Argo CD 대시보드에서 Sync 버튼 클릭

체크리스트

배포 전 확인사항:

  • Jenkinsfile 수정 완료 (단일 이미지 빌드)
  • Dockerfile 확인 (멀티스테이지 빌드)
  • values_vexplor.yaml 작성 및 업로드
  • Jenkins 프로젝트 생성
  • Argo CD 애플리케이션 등록
  • 환경 변수 설정 (DATABASE_HOST 등)
  • Secret 생성 (DB 비밀번호 등)
  • Ingress 도메인 설정
  • 헬스체크 엔드포인트 확인 (/api/health)

참고 자료

  • Kaniko: 컨테이너 내에서 Docker 이미지를 빌드하는 도구
  • GitOps: Git을 Single Source of Truth로 사용하는 배포 방식
  • Argo CD: GitOps를 위한 Kubernetes CD 도구
  • Helm: Kubernetes 패키지 매니저

담당자 연락처

  • NCP 클러스터 관리: 김욱동 책임 (엘에스티라유텍)
  • Bastion 서버: 223.130.135.25:22 (Docker 직접 배포용 아님)
  • Argo CD: https://argocd.kpslp.kr
  • Kubernetes 네임스페이스: apps

추가 설정 (선택사항)

PostgreSQL 데이터베이스 설정

클러스터 내부에 PostgreSQL이 없다면:

# values_vexplor.yaml 에 추가
postgresql:
  enabled: true
  auth:
    username: vexplor
    password: changeme123  # Secret으로 관리 권장
    database: vexplor
  primary:
    persistence:
      enabled: true
      size: 10Gi

Secret 생성 (민감 정보)

kubectl create secret generic vexplor-secrets \
  --from-literal=db-password='your-secure-password' \
  --from-literal=jwt-secret='your-jwt-secret' \
  -n apps

모니터링 (Prometheus + Grafana)

담당자에게 메트릭 수집 설정 요청

Reference in New Issue View Git Blame Copy Permalink