e008f17457
- Created 5-node KIND cluster (1 control-plane + 4 workers) - Configured NodePort mappings for console access (30080, 30081) - Created namespace separation (site11-console, site11-pipeline) - Deployed MongoDB and Redis in KIND cluster - Deployed Console backend and frontend with NodePort services - All 4 pods running successfully and verified with browser test Infrastructure: - k8s/kind-dev-cluster.yaml: 5-node cluster configuration - k8s/kind/console-mongodb-redis.yaml: Database deployments - k8s/kind/console-backend.yaml: Backend with NodePort - k8s/kind/console-frontend.yaml: Frontend with NodePort Management Tools: - scripts/kind-setup.sh: Comprehensive cluster management script - docker-compose.kubernetes.yml: Monitoring helper services Documentation: - KUBERNETES.md: Complete usage guide for developers - docs/KIND_SETUP.md: Detailed KIND setup documentation - docs/PROGRESS.md: Updated with KIND cluster completion Console Services Access: - Frontend: http://localhost:3000 (NodePort 30080) - Backend: http://localhost:8000 (NodePort 30081) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
340 lines
7.6 KiB
Markdown
340 lines
7.6 KiB
Markdown
# Kubernetes Development Environment (KIND)
|
|
|
|
Site11 프로젝트는 KIND (Kubernetes IN Docker)를 사용하여 로컬 Kubernetes 개발 환경을 구성합니다.
|
|
|
|
## 목차
|
|
- [사전 요구사항](#사전-요구사항)
|
|
- [빠른 시작](#빠른-시작)
|
|
- [관리 방법](#관리-방법)
|
|
- [접속 정보](#접속-정보)
|
|
- [문제 해결](#문제-해결)
|
|
|
|
## 사전 요구사항
|
|
|
|
다음 도구들이 설치되어 있어야 합니다:
|
|
|
|
```bash
|
|
# Docker Desktop
|
|
brew install --cask docker
|
|
|
|
# KIND
|
|
brew install kind
|
|
|
|
# kubectl
|
|
brew install kubectl
|
|
```
|
|
|
|
## 빠른 시작
|
|
|
|
### 방법 1: 스크립트 사용 (권장)
|
|
|
|
```bash
|
|
# 전체 환경 한번에 설정 (클러스터 생성 + 서비스 배포)
|
|
./scripts/kind-setup.sh setup
|
|
|
|
# 상태 확인
|
|
./scripts/kind-setup.sh status
|
|
|
|
# 접속 정보 확인
|
|
./scripts/kind-setup.sh access
|
|
```
|
|
|
|
### 방법 2: docker-compose 사용
|
|
|
|
```bash
|
|
# 헬퍼 컨테이너 시작 (모니터링 포함)
|
|
docker-compose -f docker-compose.kubernetes.yml up -d
|
|
|
|
# 모니터링 로그 확인
|
|
docker-compose -f docker-compose.kubernetes.yml logs -f kind-monitor
|
|
|
|
# 헬퍼 컨테이너 중지
|
|
docker-compose -f docker-compose.kubernetes.yml down
|
|
```
|
|
|
|
**참고**: KIND 클러스터 자체는 여전히 `kind` CLI 또는 스크립트로 관리해야 합니다. docker-compose는 모니터링 및 관리 헬퍼만 제공합니다.
|
|
|
|
### 방법 3: 수동 설정
|
|
|
|
```bash
|
|
# 1. 클러스터 생성
|
|
kind create cluster --config k8s/kind-dev-cluster.yaml
|
|
|
|
# 2. 네임스페이스 생성
|
|
kubectl create namespace site11-console
|
|
kubectl create namespace site11-pipeline
|
|
|
|
# 3. Docker 이미지 로드
|
|
kind load docker-image yakenator/site11-console-backend:latest --name site11-dev
|
|
kind load docker-image yakenator/site11-console-frontend:latest --name site11-dev
|
|
|
|
# 4. 서비스 배포
|
|
kubectl apply -f k8s/kind/console-mongodb-redis.yaml
|
|
kubectl apply -f k8s/kind/console-backend.yaml
|
|
kubectl apply -f k8s/kind/console-frontend.yaml
|
|
|
|
# 5. 상태 확인
|
|
kubectl get pods -n site11-console
|
|
```
|
|
|
|
## 관리 방법
|
|
|
|
### 스크립트 명령어
|
|
|
|
```bash
|
|
# 클러스터 생성
|
|
./scripts/kind-setup.sh create
|
|
|
|
# 클러스터 삭제
|
|
./scripts/kind-setup.sh delete
|
|
|
|
# 네임스페이스 생성
|
|
./scripts/kind-setup.sh deploy-namespaces
|
|
|
|
# Docker 이미지 로드
|
|
./scripts/kind-setup.sh load-images
|
|
|
|
# Console 서비스 배포
|
|
./scripts/kind-setup.sh deploy-console
|
|
|
|
# 상태 확인
|
|
./scripts/kind-setup.sh status
|
|
|
|
# Pod 로그 확인
|
|
./scripts/kind-setup.sh logs site11-console [pod-name]
|
|
|
|
# 접속 정보 표시
|
|
./scripts/kind-setup.sh access
|
|
```
|
|
|
|
### kubectl 명령어
|
|
|
|
```bash
|
|
# 전체 리소스 확인
|
|
kubectl get all -n site11-console
|
|
|
|
# Pod 상세 정보
|
|
kubectl describe pod <pod-name> -n site11-console
|
|
|
|
# Pod 로그 확인
|
|
kubectl logs <pod-name> -n site11-console -f
|
|
|
|
# Pod 내부 접속
|
|
kubectl exec -it <pod-name> -n site11-console -- /bin/bash
|
|
|
|
# 서비스 확인
|
|
kubectl get svc -n site11-console
|
|
|
|
# 노드 확인
|
|
kubectl get nodes
|
|
```
|
|
|
|
## 클러스터 구성
|
|
|
|
### 노드 구성 (5 노드)
|
|
|
|
- **Control Plane (1개)**: 클러스터 마스터 노드
|
|
- NodePort 매핑: 30080 → 3000 (Frontend), 30081 → 8000 (Backend)
|
|
|
|
- **Worker Nodes (4개)**:
|
|
- `workload=console`: Console 서비스 전용
|
|
- `workload=pipeline-collector`: 데이터 수집 서비스
|
|
- `workload=pipeline-processor`: 데이터 처리 서비스
|
|
- `workload=pipeline-generator`: 콘텐츠 생성 서비스
|
|
|
|
### 네임스페이스
|
|
|
|
- `site11-console`: Console 프론트엔드/백엔드, MongoDB, Redis
|
|
- `site11-pipeline`: Pipeline 관련 서비스들
|
|
|
|
## 접속 정보
|
|
|
|
### Console Services
|
|
|
|
- **Frontend**: http://localhost:3000
|
|
- NodePort: 30080
|
|
- 컨테이너 포트: 80
|
|
|
|
- **Backend**: http://localhost:8000
|
|
- NodePort: 30081
|
|
- 컨테이너 포트: 8000
|
|
|
|
### 내부 서비스 (Pod 내부에서만 접근 가능)
|
|
|
|
- **MongoDB**: `mongodb://mongodb:27017`
|
|
- **Redis**: `redis://redis:6379`
|
|
|
|
## 개발 워크플로우
|
|
|
|
### 1. 코드 변경 후 배포
|
|
|
|
```bash
|
|
# 1. Docker 이미지 빌드
|
|
docker build -t yakenator/site11-console-backend:latest \
|
|
-f services/console/backend/Dockerfile \
|
|
services/console/backend
|
|
|
|
# 2. KIND 클러스터에 이미지 로드
|
|
kind load docker-image yakenator/site11-console-backend:latest --name site11-dev
|
|
|
|
# 3. Pod 재시작
|
|
kubectl rollout restart deployment/console-backend -n site11-console
|
|
|
|
# 4. 배포 상태 확인
|
|
kubectl rollout status deployment/console-backend -n site11-console
|
|
```
|
|
|
|
### 2. 스크립트로 간편하게
|
|
|
|
```bash
|
|
# 이미지 빌드 후 로드
|
|
./scripts/kind-setup.sh load-images
|
|
|
|
# 배포 재시작
|
|
kubectl rollout restart deployment/console-backend -n site11-console
|
|
kubectl rollout restart deployment/console-frontend -n site11-console
|
|
```
|
|
|
|
### 3. 전체 재배포
|
|
|
|
```bash
|
|
# 클러스터 삭제 후 재생성
|
|
./scripts/kind-setup.sh delete
|
|
./scripts/kind-setup.sh setup
|
|
```
|
|
|
|
## 모니터링
|
|
|
|
### docker-compose 모니터링 사용
|
|
|
|
```bash
|
|
# 모니터링 시작
|
|
docker-compose -f docker-compose.kubernetes.yml up -d
|
|
|
|
# 실시간 로그 확인 (30초마다 업데이트)
|
|
docker-compose -f docker-compose.kubernetes.yml logs -f kind-monitor
|
|
```
|
|
|
|
모니터링 컨테이너는 다음 정보를 30초마다 출력합니다:
|
|
- 노드 상태
|
|
- Console 네임스페이스 Pod 상태
|
|
- Pipeline 네임스페이스 Pod 상태
|
|
|
|
## 문제 해결
|
|
|
|
### Pod이 시작되지 않는 경우
|
|
|
|
```bash
|
|
# Pod 상태 확인
|
|
kubectl get pods -n site11-console
|
|
|
|
# Pod 상세 정보 확인
|
|
kubectl describe pod <pod-name> -n site11-console
|
|
|
|
# Pod 로그 확인
|
|
kubectl logs <pod-name> -n site11-console
|
|
```
|
|
|
|
### 이미지 Pull 에러
|
|
|
|
```bash
|
|
# 로컬 이미지 확인
|
|
docker images | grep site11
|
|
|
|
# 이미지가 없으면 빌드
|
|
docker build -t yakenator/site11-console-backend:latest \
|
|
-f services/console/backend/Dockerfile \
|
|
services/console/backend
|
|
|
|
# KIND에 이미지 로드
|
|
kind load docker-image yakenator/site11-console-backend:latest --name site11-dev
|
|
```
|
|
|
|
### NodePort 접속 불가
|
|
|
|
```bash
|
|
# 서비스 확인
|
|
kubectl get svc -n site11-console
|
|
|
|
# NodePort 확인 (30080, 30081이어야 함)
|
|
kubectl describe svc console-frontend -n site11-console
|
|
kubectl describe svc console-backend -n site11-console
|
|
|
|
# 포트 포워딩 대안 (문제가 계속되면)
|
|
kubectl port-forward svc/console-frontend 3000:3000 -n site11-console
|
|
kubectl port-forward svc/console-backend 8000:8000 -n site11-console
|
|
```
|
|
|
|
### 클러스터 완전 초기화
|
|
|
|
```bash
|
|
# KIND 클러스터 삭제
|
|
kind delete cluster --name site11-dev
|
|
|
|
# Docker 네트워크 정리 (필요시)
|
|
docker network prune -f
|
|
|
|
# 클러스터 재생성
|
|
./scripts/kind-setup.sh setup
|
|
```
|
|
|
|
### MongoDB 연결 실패
|
|
|
|
```bash
|
|
# MongoDB Pod 확인
|
|
kubectl get pod -n site11-console -l app=mongodb
|
|
|
|
# MongoDB 로그 확인
|
|
kubectl logs -n site11-console -l app=mongodb
|
|
|
|
# MongoDB 서비스 확인
|
|
kubectl get svc mongodb -n site11-console
|
|
|
|
# Pod 내에서 연결 테스트
|
|
kubectl exec -it <console-backend-pod> -n site11-console -- \
|
|
curl mongodb:27017
|
|
```
|
|
|
|
## 참고 문서
|
|
|
|
- [KIND 공식 문서](https://kind.sigs.k8s.io/)
|
|
- [Kubernetes 공식 문서](https://kubernetes.io/docs/)
|
|
- [KIND 설정 가이드](./docs/KIND_SETUP.md)
|
|
|
|
## 유용한 팁
|
|
|
|
### kubectl 자동완성 설정
|
|
|
|
```bash
|
|
# Bash
|
|
echo 'source <(kubectl completion bash)' >>~/.bashrc
|
|
|
|
# Zsh
|
|
echo 'source <(kubectl completion zsh)' >>~/.zshrc
|
|
```
|
|
|
|
### kubectl 단축어 설정
|
|
|
|
```bash
|
|
# ~/.bashrc 또는 ~/.zshrc에 추가
|
|
alias k='kubectl'
|
|
alias kgp='kubectl get pods'
|
|
alias kgs='kubectl get svc'
|
|
alias kgn='kubectl get nodes'
|
|
alias kl='kubectl logs'
|
|
alias kd='kubectl describe'
|
|
```
|
|
|
|
### Context 빠른 전환
|
|
|
|
```bash
|
|
# 현재 context 확인
|
|
kubectl config current-context
|
|
|
|
# KIND context로 전환
|
|
kubectl config use-context kind-site11-dev
|
|
|
|
# 기본 namespace 설정
|
|
kubectl config set-context --current --namespace=site11-console
|
|
```
|