ERP-node/DEPLOYMENT_GUIDE_KPSLP.md

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

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

## 전제 조건

### 1. GitLab 레포지토리
- [x] 프로젝트 코드 레포: 이미 생성됨 (현재 레포)
- [ ] 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 빌드 트리거
```bash
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 상태 확인
```bash
kubectl get pods -n apps | grep vexplor
```
**예상 출력**:
```
vexplor-xxxxxxxxxx-xxxxx   1/1     Running   0          2m
```

### 2. 서비스 확인
```bash
kubectl get svc -n apps | grep vexplor
```

### 3. Ingress 확인
```bash
kubectl get ingress -n apps | grep vexplor
```

### 4. 로그 확인
```bash
# 전체 로그
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`이 프로젝트 루트에 있는지 확인
- 빌드 컨텍스트에 필요한 파일들이 있는지 확인

**해결**:
```bash
# 로컬에서 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가 계속 재시작됨

**확인**:
```bash
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 비밀번호 등)

---

## 업데이트 배포 프로세스

코드 수정 후 배포 절차:

```bash
# 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이 없다면:

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

### Secret 생성 (민감 정보)
```bash
kubectl create secret generic vexplor-secrets \
  --from-literal=db-password='your-secure-password' \
  --from-literal=jwt-secret='your-jwt-secret' \
  -n apps
```

### 모니터링 (Prometheus + Grafana)
담당자에게 메트릭 수집 설정 요청