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)

가장 간단하고 안정적인 방법입니다.

# 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

로컬 개발 환경용 (복잡함)

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

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

장점:

• 인터넷 연결 불필요
• 빠른 이미지 전송

단점:

• Docker Desktop K8s 제한사항
• 추가 설정 필요

Option 3: Kind Cluster

고급 사용자용

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

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

장점:

• 완전한 K8s 환경
• 로컬 이미지 직접 사용 가능

단점:

• Kind 설치 필요
• 리소스 사용량 높음

Infrastructure Setup

1. Start Infrastructure Services

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

2. Verify Infrastructure

# 서비스 상태 확인
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

kubectl -n site11-pipeline get pods -w

View Logs

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

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

Check Auto-scaling

kubectl -n site11-pipeline get hpa

Monitor Queue Status

docker-compose -f docker-compose-hybrid.yml logs -f pipeline-monitor

Scaling

Manual Scaling

# 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

kubectl delete namespace site11-pipeline

Stop Infrastructure

docker-compose -f docker-compose-hybrid.yml down

Remove Kind Cluster (if used)

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 정기 백업 설정