site11/k8s/K8S-DEPLOYMENT-GUIDE.md

# K8S-DEPLOYMENT-GUIDE

## Overview
Site11 파이프라인 시스템의 K8s 배포 가이드입니다. AWS 프로덕션 환경과 유사하게 인프라는 K8s 외부에, 워커들은 K8s 내부에 배포합니다.

## Architecture
```
┌─────────────────────────────────────────────────┐
│                  Docker Compose                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐        │
│  │ MongoDB  │ │  Redis   │ │  Kafka   │        │
│  └──────────┘ └──────────┘ └──────────┘        │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐        │
│  │Scheduler │ │ Monitor  │ │Lang Sync │        │
│  └──────────┘ └──────────┘ └──────────┘        │
└─────────────────────────────────────────────────┘
                          ↕
┌─────────────────────────────────────────────────┐
│                   Kubernetes                     │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐        │
│  │   RSS    │ │  Search  │ │Translator│        │
│  └──────────┘ └──────────┘ └──────────┘        │
│  ┌──────────┐ ┌──────────┐                     │
│  │ AI Gen   │ │Image Gen │                     │
│  └──────────┘ └──────────┘                     │
└─────────────────────────────────────────────────┘
```

## Deployment Options

### Option 1: Docker Hub (Recommended)
가장 간단하고 안정적인 방법입니다.

```bash
# 1. Docker Hub 계정 설정
export DOCKER_HUB_USER=your-username

# 2. Docker Hub 로그인
docker login

# 3. 배포 실행
cd k8s/pipeline
./deploy-dockerhub.sh
```

**장점:**
- 설정이 간단함
- 어떤 K8s 클러스터에서도 작동
- 이미지 버전 관리 용이

**단점:**
- Docker Hub 계정 필요
- 이미지 업로드 시간 소요

### Option 2: Local Registry
로컬 개발 환경용 (복잡함)

```bash
# 1. 로컬 레지스트리 시작
docker-compose -f docker-compose-hybrid.yml up -d registry

# 2. 이미지 태그 및 푸시
./deploy-local.sh
```

**장점:**
- 인터넷 연결 불필요
- 빠른 이미지 전송

**단점:**
- Docker Desktop K8s 제한사항
- 추가 설정 필요

### Option 3: Kind Cluster
고급 사용자용

```bash
# 1. Kind 클러스터 생성
kind create cluster --config kind-config.yaml

# 2. 이미지 로드 및 배포
./deploy-kind.sh
```

**장점:**
- 완전한 K8s 환경
- 로컬 이미지 직접 사용 가능

**단점:**
- Kind 설치 필요
- 리소스 사용량 높음

## Infrastructure Setup

### 1. Start Infrastructure Services
```bash
# 인프라 서비스 시작 (MongoDB, Redis, Kafka, etc.)
docker-compose -f docker-compose-hybrid.yml up -d
```

### 2. Verify Infrastructure
```bash
# 서비스 상태 확인
docker ps | grep site11

# 로그 확인
docker-compose -f docker-compose-hybrid.yml logs -f
```

## Common Issues

### Issue 1: ImagePullBackOff
**원인:** K8s가 이미지를 찾을 수 없음
**해결:** Docker Hub 사용 또는 Kind 클러스터 사용

### Issue 2: Connection to External Services Failed
**원인:** K8s Pod에서 Docker 서비스 접근 불가
**해결:** `host.docker.internal` 사용 확인

### Issue 3: Pods Not Starting
**원인:** 리소스 부족
**해결:** 리소스 limits 조정 또는 노드 추가

## Monitoring

### View Pod Status
```bash
kubectl -n site11-pipeline get pods -w
```

### View Logs
```bash
# 특정 서비스 로그
kubectl -n site11-pipeline logs -f deployment/pipeline-translator

# 모든 Pod 로그
kubectl -n site11-pipeline logs -l app=pipeline-translator
```

### Check Auto-scaling
```bash
kubectl -n site11-pipeline get hpa
```

### Monitor Queue Status
```bash
docker-compose -f docker-compose-hybrid.yml logs -f pipeline-monitor
```

## Scaling

### Manual Scaling
```bash
# Scale up
kubectl -n site11-pipeline scale deployment pipeline-translator --replicas=5

# Scale down
kubectl -n site11-pipeline scale deployment pipeline-translator --replicas=2
```

### Auto-scaling Configuration
HPA는 CPU 70%, Memory 80% 기준으로 자동 확장됩니다.

## Cleanup

### Remove K8s Resources
```bash
kubectl delete namespace site11-pipeline
```

### Stop Infrastructure
```bash
docker-compose -f docker-compose-hybrid.yml down
```

### Remove Kind Cluster (if used)
```bash
kind delete cluster --name site11-cluster
```

## Production Deployment

실제 AWS 프로덕션 환경에서는:
1. MongoDB → Amazon DocumentDB
2. Redis → Amazon ElastiCache
3. Kafka → Amazon MSK
4. Local Registry → Amazon ECR
5. K8s → Amazon EKS

ConfigMap에서 연결 정보만 변경하면 됩니다.

## Best Practices

1. **이미지 버전 관리**: latest 대신 구체적인 버전 태그 사용
2. **리소스 제한**: 적절한 requests/limits 설정
3. **모니터링**: Prometheus/Grafana 등 모니터링 도구 설치
4. **로그 관리**: 중앙 로그 수집 시스템 구축
5. **백업**: MongoDB 정기 백업 설정