# vexplor 쿠버네티스 자동 배포 가이드 ## 개요 이 문서는 vexplor 프로젝트를 Gitea Actions를 통해 쿠버네티스 클러스터에 자동 배포하는 방법을 설명합니다. **작성일**: 2024년 12월 22일 --- ## 아키텍처 ``` ┌─────────────────────────────────────────────────────────────────┐ │ Gitea Repository │ │ g.wace.me/chpark/vexplor │ └─────────────────────┬───────────────────────────────────────────┘ │ push to main ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Gitea Actions Runner │ │ 1. Checkout code │ │ 2. Build Docker images (frontend, backend) │ │ 3. Push to Harbor Registry │ │ 4. Deploy to Kubernetes │ └─────────────────────┬───────────────────────────────────────────┘ │ ┌──────────┴──────────┐ ▼ ▼ ┌──────────────────┐ ┌──────────────────┐ │ Harbor Registry │ │ Kubernetes (K8s) │ │ harbor.wace.me │ │ 112.168.212.142 │ └──────────────────┘ └──────────────────┘ │ ┌────────────────┼────────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Frontend │ │ Backend │ │ Ingress │ │ :3000 │ │ :3001 │ │ Nginx │ └──────────┘ └──────────┘ └──────────┘ │ │ │ └────────────────┴────────────────┘ │ ▼ ┌─────────────────────┐ │ External Access │ │ v1.vexplor.com │ │ api.vexplor.com │ └─────────────────────┘ ``` --- ## 사전 요구사항 ### 1. 쿠버네티스 클러스터 ```bash # 서버 정보 IP: 112.168.212.142 SSH: ssh -p 22 wace@112.168.212.142 K8s 버전: v1.28.15 ``` ### 2. Harbor 레지스트리 접근 권한 Harbor에 `vexplor` 프로젝트가 생성되어 있어야 합니다. ### 3. Gitea Repository Secrets Gitea 저장소에 다음 Secrets를 설정해야 합니다: | Secret 이름 | 설명 | |------------|------| | `HARBOR_USERNAME` | Harbor 사용자명 | | `HARBOR_PASSWORD` | Harbor 비밀번호 | | `KUBECONFIG` | base64 인코딩된 Kubernetes config | --- ## 초기 설정 ### 1단계: 쿠버네티스 클러스터 접속 ```bash ssh -p 22 wace@112.168.212.142 ``` ### 2단계: Nginx Ingress Controller 설치 ```bash # Nginx Ingress Controller 설치 (baremetal용) kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.9.5/deploy/static/provider/baremetal/deploy.yaml # 설치 확인 kubectl get pods -n ingress-nginx kubectl get svc -n ingress-nginx ``` ### 3단계: Local Path Provisioner 설치 (PVC용) ```bash # Local Path Provisioner 설치 kubectl apply -f k8s/local-path-provisioner.yaml # 설치 확인 kubectl get pods -n local-path-storage kubectl get storageclass ``` ### 4단계: Cert-Manager 설치 (SSL 인증서용) ```bash # Cert-Manager 설치 kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.3/cert-manager.yaml # 설치 확인 kubectl get pods -n cert-manager # ClusterIssuer 생성 (Let's Encrypt) cat < Secrets > Actions 메뉴로 이동 3. 다음 Secrets 추가: #### HARBOR_USERNAME Harbor 로그인 사용자명 #### HARBOR_PASSWORD Harbor 로그인 비밀번호 #### KUBECONFIG ```bash # 쿠버네티스 서버에서 실행 cat ~/.kube/config | base64 -w 0 ``` 출력된 값을 KUBECONFIG secret으로 등록 --- ## 배포 트리거 ### 자동 배포 (Push) 다음 경로의 파일이 변경되어 `main` 브랜치에 push되면 자동으로 배포됩니다: - `backend-node/**` - `frontend/**` - `docker/**` - `k8s/**` - `.gitea/workflows/deploy.yml` ### 수동 배포 1. Gitea 저장소 > Actions 탭으로 이동 2. "Deploy vexplor" 워크플로우 선택 3. "Run workflow" 버튼 클릭 --- ## 파일 구조 ``` vexplor/ ├── .gitea/ │ └── workflows/ │ └── deploy.yml # Gitea Actions 워크플로우 ├── docker/ │ └── deploy/ │ ├── backend.Dockerfile # 백엔드 배포용 Dockerfile │ └── frontend.Dockerfile # 프론트엔드 배포용 Dockerfile ├── k8s/ │ ├── namespace.yaml # 네임스페이스 정의 │ ├── vexplor-config.yaml # ConfigMap │ ├── vexplor-secret.yaml.template # Secret 템플릿 │ ├── vexplor-backend-deployment.yaml # 백엔드 Deployment/Service/PVC │ ├── vexplor-frontend-deployment.yaml # 프론트엔드 Deployment/Service │ ├── vexplor-ingress.yaml # Ingress 설정 │ ├── local-path-provisioner.yaml # 스토리지 프로비저너 │ └── ingress-nginx.yaml # Ingress 컨트롤러 패치 └── docs/ └── KUBERNETES_DEPLOYMENT_GUIDE.md # 이 문서 ``` --- ## 운영 명령어 ### 상태 확인 ```bash # 전체 리소스 확인 kubectl get all -n vexplor # Pod 상태 확인 kubectl get pods -n vexplor -o wide # 로그 확인 kubectl logs -f deployment/vexplor-backend -n vexplor kubectl logs -f deployment/vexplor-frontend -n vexplor # Pod 상세 정보 kubectl describe pod -n vexplor ``` ### 수동 배포/롤백 ```bash # 이미지 업데이트 kubectl set image deployment/vexplor-backend \ vexplor-backend=harbor.wace.me/vexplor/vexplor-backend:v20241222-120000-abc1234 \ -n vexplor # 롤아웃 상태 확인 kubectl rollout status deployment/vexplor-backend -n vexplor # 롤백 kubectl rollout undo deployment/vexplor-backend -n vexplor kubectl rollout undo deployment/vexplor-frontend -n vexplor # 히스토리 확인 kubectl rollout history deployment/vexplor-backend -n vexplor ``` ### 스케일링 ```bash # 레플리카 수 조정 kubectl scale deployment/vexplor-backend --replicas=3 -n vexplor kubectl scale deployment/vexplor-frontend --replicas=3 -n vexplor ``` ### Pod 재시작 ```bash # Deployment 재시작 (롤링 업데이트) kubectl rollout restart deployment/vexplor-backend -n vexplor kubectl rollout restart deployment/vexplor-frontend -n vexplor ``` --- ## 문제 해결 ### Pod이 Pending 상태일 때 ```bash # Pod 이벤트 확인 kubectl describe pod -n vexplor # 노드 리소스 확인 kubectl describe node kubectl top nodes ``` ### ImagePullBackOff 오류 ```bash # Harbor Secret 확인 kubectl get secret harbor-registry -n vexplor -o yaml # Secret 재생성 kubectl delete secret harbor-registry -n vexplor kubectl create secret docker-registry harbor-registry \ --docker-server=192.168.1.100:5001 \ --docker-username= \ --docker-password= \ -n vexplor ``` ### Ingress가 작동하지 않을 때 ```bash # Ingress 상태 확인 kubectl get ingress -n vexplor kubectl describe ingress vexplor-ingress -n vexplor # Ingress Controller 로그 kubectl logs -f deployment/ingress-nginx-controller -n ingress-nginx ``` ### SSL 인증서 문제 ```bash # Certificate 상태 확인 kubectl get certificate -n vexplor kubectl describe certificate vexplor-tls -n vexplor # Cert-Manager 로그 kubectl logs -f deployment/cert-manager -n cert-manager ``` --- ## 네트워크 설정 ### 방화벽 포트 개방 쿠버네티스 서버에서 다음 포트가 개방되어야 합니다: | 포트 | 용도 | |-----|------| | 30080 | HTTP (Ingress NodePort) | | 30443 | HTTPS (Ingress NodePort) | | 6443 | Kubernetes API | ### DNS 설정 다음 도메인이 쿠버네티스 서버 IP를 가리키도록 설정: - `v1.vexplor.com` → 112.168.212.142 - `api.vexplor.com` → 112.168.212.142 --- ## 환경 변수 ### Backend 환경 변수 | 변수 | 설명 | 소스 | |-----|------|-----| | `NODE_ENV` | 환경 (production) | ConfigMap | | `PORT` | 서버 포트 (3001) | ConfigMap | | `DATABASE_URL` | PostgreSQL 연결 문자열 | Secret | | `JWT_SECRET` | JWT 서명 키 | Secret | | `JWT_EXPIRES_IN` | JWT 만료 시간 | ConfigMap | | `CORS_ORIGIN` | CORS 허용 도메인 | ConfigMap | ### Frontend 환경 변수 | 변수 | 설명 | 소스 | |-----|------|-----| | `NODE_ENV` | 환경 (production) | ConfigMap | | `NEXT_PUBLIC_API_URL` | 클라이언트 API URL | ConfigMap | | `SERVER_API_URL` | SSR용 내부 API URL | Deployment | --- ## 참고 자료 - [Kubernetes 공식 문서](https://kubernetes.io/docs/) - [Gitea Actions 문서](https://docs.gitea.com/usage/actions/overview) - [Nginx Ingress Controller](https://kubernetes.github.io/ingress-nginx/) - [Cert-Manager](https://cert-manager.io/docs/) - [Harbor Registry](https://goharbor.io/docs/)