site11/docs/DEPLOYMENT_GUIDE.md

Site11 배포 가이드

📋 목차

• 배포 아키텍처
• 배포 옵션
• 하이브리드 배포 (권장)
• 포트 구성
• Health Check
• 문제 해결

배포 아키텍처

현재 구성: 하이브리드 아키텍처

┌─────────────────────────────────────────────────────────┐
│                    사용자 브라우저                         │
└────────────┬────────────────────┬──────────────────────┘
             │                    │
        localhost:8080       localhost:8000
             │                    │
    ┌────────┴──────────┐ ┌──────┴──────────┐
    │ kubectl           │ │ kubectl         │
    │ port-forward      │ │ port-forward    │
    └────────┬──────────┘ └──────┬──────────┘
             │                    │
    ┌────────┴──────────────────┴──────────┐
    │        Kubernetes Cluster (Kind)      │
    │                                        │
    │  ┌──────────────┐  ┌──────────────┐  │
    │  │ Console      │  │ Console      │  │
    │  │ Frontend     │  │ Backend      │  │
    │  │ Service:3000 │  │ Service:8000 │  │
    │  └──────┬───────┘  └──────┬───────┘  │
    │         │                  │          │
    │  ┌──────┴───────┐  ┌──────┴───────┐  │
    │  │ nginx:80     │  │ FastAPI:8000 │  │
    │  │ (Pod)        │  │ (Pod)        │  │
    │  └──────────────┘  └──────┬───────┘  │
    │                            │          │
    │  ┌─────────────────────────┴───────┐  │
    │  │ Pipeline Workers (5 Deployments) │  │
    │  └──────────────┬──────────────────┘  │
    └─────────────────┼──────────────────┘
                      │
         host.docker.internal
                      │
    ┌─────────────────┴──────────────────┐
    │     Docker Compose Infrastructure   │
    │                                      │
    │  MongoDB | Redis | Kafka | Zookeeper│
    │  Pipeline Scheduler | Monitor        │
    └──────────────────────────────────────┘

배포 옵션

옵션 1: 하이브리드 배포 (현재/권장)

• Docker Compose: 인프라 서비스 (MongoDB, Redis, Kafka)
• Kubernetes: 애플리케이션 및 파이프라인 워커
• 장점: 프로덕션 환경과 유사, 확장성 우수
• 단점: 설정 복잡도 높음

옵션 2: 전체 Docker Compose

• 모든 서비스를 Docker Compose로 실행
• 장점: 설정 간단, 로컬 개발에 최적
• 단점: 오토스케일링 제한

옵션 3: 전체 Kubernetes

• 모든 서비스를 Kubernetes로 실행
• 장점: 완전한 클라우드 네이티브
• 단점: 로컬 리소스 많이 필요

하이브리드 배포 (권장)

1. 인프라 시작 (Docker Compose)

# Docker Compose로 인프라 서비스 시작
docker-compose -f docker-compose-hybrid.yml up -d

# 상태 확인
docker-compose -f docker-compose-hybrid.yml ps

# 서비스 확인
docker ps | grep -E "mongodb|redis|kafka|zookeeper|scheduler|monitor"

2. Kubernetes 클러스터 준비

# Docker Desktop Kubernetes 활성화 또는 Kind 사용
# Docker Desktop: Preferences → Kubernetes → Enable Kubernetes

# 네임스페이스 생성
kubectl create namespace site11-pipeline

# ConfigMap 및 Secrets 생성
kubectl -n site11-pipeline apply -f k8s/pipeline/configmap.yaml
kubectl -n site11-pipeline apply -f k8s/pipeline/secrets.yaml

3. 애플리케이션 배포 (Docker Hub)

# Docker Hub에 이미지 푸시
export DOCKER_HUB_USER=yakenator
./deploy-dockerhub.sh

# Kubernetes에 배포
cd k8s/pipeline
for yaml in *-dockerhub.yaml; do
  kubectl apply -f $yaml
done

# 배포 확인
kubectl -n site11-pipeline get deployments
kubectl -n site11-pipeline get pods
kubectl -n site11-pipeline get services

4. Port Forwarding 설정

# 자동 스크립트 사용
./scripts/start-k8s-port-forward.sh

# 또는 수동 설정
kubectl -n site11-pipeline port-forward service/console-frontend 8080:3000 &
kubectl -n site11-pipeline port-forward service/console-backend 8000:8000 &

포트 구성

하이브리드 배포 포트 매핑

서비스	로컬 포트	Service 포트	Pod 포트	설명
Console Frontend	8080	3000	80	nginx 정적 파일 서빙
Console Backend	8000	8000	8000	FastAPI API Gateway
Pipeline Monitor	8100	-	8100	Docker 직접 노출
Pipeline Scheduler	8099	-	8099	Docker 직접 노출
MongoDB	27017	-	27017	Docker 내부
Redis	6379	-	6379	Docker 내부
Kafka	9092	-	9092	Docker 내부

Port Forward 체인

사용자 → localhost:8080 → kubectl port-forward → K8s Service:3000 → Pod nginx:80

Health Check

Console 서비스 Health Check

# Console Backend Health
curl http://localhost:8000/health
curl http://localhost:8000/api/health

# Console Frontend Health (HTML 응답)
curl http://localhost:8080/

# Users Service Health (via Console Backend)
curl http://localhost:8000/api/users/health

Pipeline 서비스 Health Check

# Pipeline Monitor
curl http://localhost:8100/health

# Pipeline Scheduler
curl http://localhost:8099/health

Kubernetes Health Check

# Pod 상태
kubectl -n site11-pipeline get pods -o wide

# 서비스 엔드포인트
kubectl -n site11-pipeline get endpoints

# HPA 상태
kubectl -n site11-pipeline get hpa

# 이벤트 확인
kubectl -n site11-pipeline get events --sort-by='.lastTimestamp'

스케일링

Horizontal Pod Autoscaler (HPA)

서비스	최소	최대	CPU 목표	메모리 목표
Console Frontend	2	10	70%	80%
Console Backend	2	10	70%	80%
RSS Collector	1	5	70%	80%
Google Search	1	5	70%	80%
Translator	3	10	70%	80%
AI Generator	2	10	70%	80%
Image Generator	2	10	70%	80%

수동 스케일링

# 특정 디플로이먼트 스케일 조정
kubectl -n site11-pipeline scale deployment/pipeline-translator --replicas=5

# 모든 파이프라인 워커 스케일 업
for deploy in rss-collector google-search translator ai-article-generator image-generator; do
  kubectl -n site11-pipeline scale deployment/pipeline-$deploy --replicas=3
done

모니터링

실시간 모니터링

# Pod 리소스 사용량
kubectl -n site11-pipeline top pods

# 로그 스트리밍
kubectl -n site11-pipeline logs -f deployment/console-backend
kubectl -n site11-pipeline logs -f deployment/pipeline-translator

# HPA 상태 감시
watch -n 2 kubectl -n site11-pipeline get hpa

Pipeline 모니터링

# Pipeline Monitor 웹 UI
open http://localhost:8100

# Queue 상태 확인
docker exec -it site11_redis redis-cli
> LLEN queue:translation
> LLEN queue:ai_generation
> LLEN queue:image_generation

문제 해결

Pod가 시작되지 않을 때

# Pod 상세 정보
kubectl -n site11-pipeline describe pod <pod-name>

# 이미지 풀 에러 확인
kubectl -n site11-pipeline get events | grep -i pull

# 해결: Docker Hub 이미지 다시 푸시
docker push yakenator/site11-<service>:latest
kubectl -n site11-pipeline rollout restart deployment/<service>

Port Forward 연결 끊김

# 기존 port-forward 종료
pkill -f "kubectl.*port-forward"

# 다시 시작
./scripts/start-k8s-port-forward.sh

인프라 서비스 연결 실패

# Docker 네트워크 확인
docker network ls | grep site11

# K8s Pod에서 연결 테스트
kubectl -n site11-pipeline exec -it <pod-name> -- bash
> apt update && apt install -y netcat
> nc -zv host.docker.internal 6379  # Redis
> nc -zv host.docker.internal 27017 # MongoDB

Health Check 실패

# Console Backend 로그 확인
kubectl -n site11-pipeline logs deployment/console-backend --tail=50

# 엔드포인트 직접 테스트
kubectl -n site11-pipeline exec -it deployment/console-backend -- curl localhost:8000/health

정리 및 초기화

전체 정리

# Kubernetes 리소스 삭제
kubectl delete namespace site11-pipeline

# Docker Compose 정리
docker-compose -f docker-compose-hybrid.yml down

# 볼륨 포함 완전 정리 (주의!)
docker-compose -f docker-compose-hybrid.yml down -v

선택적 정리

# 특정 디플로이먼트만 삭제
kubectl -n site11-pipeline delete deployment <name>

# 특정 Docker 서비스만 중지
docker-compose -f docker-compose-hybrid.yml stop mongodb

백업 및 복구

MongoDB 백업

# 백업
docker exec site11_mongodb mongodump --archive=/tmp/backup.archive
docker cp site11_mongodb:/tmp/backup.archive ./backups/mongodb-$(date +%Y%m%d).archive

# 복구
docker cp ./backups/mongodb-20240101.archive site11_mongodb:/tmp/
docker exec site11_mongodb mongorestore --archive=/tmp/mongodb-20240101.archive

전체 설정 백업

# 설정 파일 백업
tar -czf config-backup-$(date +%Y%m%d).tar.gz \
  k8s/ \
  docker-compose*.yml \
  .env \
  registry/

다음 단계

1. 프로덕션 준비

   • Ingress Controller 설정
   • SSL/TLS 인증서
   • 외부 모니터링 통합

2. 성능 최적화

   • Registry Cache 활성화
   • 빌드 캐시 최적화
   • 리소스 리밋 조정

3. 보안 강화

   • Network Policy 적용
   • RBAC 설정
   • Secrets 암호화