site11/KUBERNETES.md

Kubernetes Development Environment (KIND)

Site11 프로젝트는 KIND (Kubernetes IN Docker)를 사용하여 로컬 Kubernetes 개발 환경을 구성합니다.

목차

• 사전 요구사항
• 빠른 시작
• 관리 방법
• 접속 정보
• 문제 해결

사전 요구사항

다음 도구들이 설치되어 있어야 합니다:

# Docker Desktop
brew install --cask docker

# KIND
brew install kind

# kubectl
brew install kubectl

빠른 시작

방법 1: 스크립트 사용 (권장)

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

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

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

방법 2: docker-compose 사용

# 헬퍼 컨테이너 시작 (모니터링 포함)
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: 수동 설정

# 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

관리 방법

스크립트 명령어

# 클러스터 생성
./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 명령어

# 전체 리소스 확인
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. 코드 변경 후 배포

# 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. 스크립트로 간편하게

# 이미지 빌드 후 로드
./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. 전체 재배포

# 클러스터 삭제 후 재생성
./scripts/kind-setup.sh delete
./scripts/kind-setup.sh setup

모니터링

docker-compose 모니터링 사용

# 모니터링 시작
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이 시작되지 않는 경우

# 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 에러

# 로컬 이미지 확인
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 접속 불가

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

클러스터 완전 초기화

# KIND 클러스터 삭제
kind delete cluster --name site11-dev

# Docker 네트워크 정리 (필요시)
docker network prune -f

# 클러스터 재생성
./scripts/kind-setup.sh setup

MongoDB 연결 실패

# 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 공식 문서
• Kubernetes 공식 문서
• KIND 설정 가이드

유용한 팁

kubectl 자동완성 설정

# Bash
echo 'source <(kubectl completion bash)' >>~/.bashrc

# Zsh
echo 'source <(kubectl completion zsh)' >>~/.zshrc

kubectl 단축어 설정

# ~/.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 빠른 전환

# 현재 context 확인
kubectl config current-context

# KIND context로 전환
kubectl config use-context kind-site11-dev

# 기본 namespace 설정
kubectl config set-context --current --namespace=site11-console