# 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: docker-compose 사용 (권장) ⭐

```bash
# 1. 관리 컨테이너 시작
docker-compose -f docker-compose.kubernetes.yml up -d

# 2. KIND 클러스터 생성 및 배포
docker-compose -f docker-compose.kubernetes.yml exec kind-cli /scripts/kind-setup.sh setup

# 3. 상태 확인
docker-compose -f docker-compose.kubernetes.yml exec kind-cli /scripts/kind-setup.sh status

# 4. 실시간 모니터링
docker-compose -f docker-compose.kubernetes.yml logs -f monitor
```

### 방법 2: 로컬 스크립트 사용

```bash
# 전체 환경 한번에 설정 (클러스터 생성 + 서비스 배포)
./scripts/kind-setup.sh setup

# 상태 확인
./scripts/kind-setup.sh status

# 접속 정보 확인
./scripts/kind-setup.sh access
```

### 방법 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
```

## 관리 방법

### docker-compose 명령어 (권장)

```bash
# 관리 컨테이너 시작
docker-compose -f docker-compose.kubernetes.yml up -d

# 클러스터 생성
docker-compose -f docker-compose.kubernetes.yml exec kind-cli /scripts/kind-setup.sh create

# 클러스터 삭제
docker-compose -f docker-compose.kubernetes.yml exec kind-cli /scripts/kind-setup.sh delete

# 전체 설정 (생성 + 배포)
docker-compose -f docker-compose.kubernetes.yml exec kind-cli /scripts/kind-setup.sh setup

# 상태 확인
docker-compose -f docker-compose.kubernetes.yml exec kind-cli /scripts/kind-setup.sh status

# 실시간 모니터링
docker-compose -f docker-compose.kubernetes.yml logs -f monitor

# kubectl 직접 사용
docker-compose -f docker-compose.kubernetes.yml exec kind-cli kubectl get pods -A

# Shell 접속
docker-compose -f docker-compose.kubernetes.yml exec kind-cli bash

# 관리 컨테이너 중지
docker-compose -f docker-compose.kubernetes.yml down
```

### 로컬 스크립트 명령어

```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
```