Kubeadm - 100-hours-a-week/21-iceT-wiki GitHub Wiki

본 문서는 AWS EC2 인스턴스 위에 구축된 기존 Docker 기반 3티어 아키텍처(Dev/Prod 환경 분리)를 Kubeadm을 활용한
Kubernetes 멀티 노드 클러스터로 확장하기 위한 설정 명세서입니다.
개발 환경과 운영 환경을 명확히 분리하고, 지속적인 배포 자동화, 가용성 확보, 리소스 탄력성 강화를 목표로 클러스터를 설계합니다.

• 목적: Dev/Prod 환경을 구분한 K8s 클러스터 기반으로 인프라의 안정성, 확장성, 무중단 배포 구조 확보
• 기존 구성: Docker 기반 EC2 3티어 아키텍처 (Frontend - Backend - MySQL), CodeDeploy 활용
• 확장 방향:
  • EC2 위 Kubeadm으로 Kubernetes 클러스터 구성 (Master + Worker)
  • CI/CD: 기존 GitHub + CodeDeploy → ArgoCD 기반 GitOps
  • DB는 Kubernetes 외부(EC2 MySQL)로 분리 유지

현재 운영 중인 서비스는 AWS EC2 인스턴스 위에 구축된 Docker 기반 3티어 아키텍처(Frontend - Backend - MySQL)로 구성되어 있으며, Dev, Stage, Prod 환경을 분리하여 각각 독립된 VPC와 EC2 인프라 상에서 운영되고 있습니다. 각 계층은 Docker Compose 방식으로 구성되어 있으며, 배포 자동화는 GitHub Actions를 통해 진행하고 있습니다.

이와 같은 아키텍처는 초기에는 단순하고 직관적인 방식이지만, 다음과 같은 확장성과 운영 측면의 한계가 나타납니다. 이를 다음과 같은 방식으로 확장을 고려할 수 있습니다.

• 수직 확장(Scale-up): EC2 인스턴스의 사양을 높임 (t3.small → t3.large)
• 수평 확장(Scale-out): EC2 인스턴스 수를 늘리고 로드 밸런서를 붙여 분산 처리

이러한 방식은 단기적으로는 유효하지만, 아래와 같은 구조적 한계를 가지고 있습니다:

• EC2 인스턴스별로 독립적인 Docker 컨테이너를 중앙 관리가 필요
• 서비스 상태를 감시 불가하기에 웹 UI/CLI로 운영을 하며 배포 상태 모니터링 필요 및 롤백 가능
• Dev/Prod 환경 간 배포 구성 및 자원 정책을 일관되게 관리하기 어려움 → Helm values, Kustomize로 Dev/Prod 환경에 같은 구조를 적용
• 서비스의 무중단 배포 필요

kubeadm을 통한 Kubernetes 클러스터 도입은 위 문제를 다음과 같이 해결할 수 있습니다.

• 다수 노드 통합 관리: Master Node를 통한 중앙 집중형 클러스터 관리
• 자원 최적화 및 오토스케일링: HPA(수평 오토스케일링)와 리소스 기반 스케줄링으로 트래픽 증감 대응
• 무중단 배포(Zero Downtime Deployment): Deployment 오브젝트를 통한 롤링 업데이트 및 버전 관리
• 서비스 복구 및 셀프 힐링(Self-healing): 노드 장애 및 파드 장애 발생 시 자동 복구
• 일관된 배포 환경: Helm Chart, Kustomize 등을 통한 Dev/Stage/Prod 환경 구성 표준화
• 네이티브 모니터링/로깅: Prometheus, Grafana, Fluent Bit 등과 연계하여 상태 감시 및 트러블슈팅 체계 구축

또한 kubeadm은 클라우드 벤더에 종속되지 않고, 직접 Kubernetes 표준 클러스터를 설치하고 제어할 수 있어 서비스 확장성 및 인프라 독립성을 동시에 확보할 수 있습니다.

구분	Deployment	DaemonSet	HPA
목적	앱 배포/관리	노드마다 1개 필수 파드 배포	파드 수 자동 스케일링
대상	서비스 앱 (Next.js, Spring 등)	시스템 에이전트 (Fluent Bit 등)	Deployment 리소스 감시
스케일링 방식	수동 설정 (replicas)	노드 수만큼 고정	트래픽 기반 자동 조정
파드 수	내가 정함 (또는 HPA가 조정)	노드 수와 같음	HPA가 자동 조정

• Master Node (Control Plane)
  • kube-apiserver
  • kube-controller-manager
  • kube-scheduler
  • etcd
• Worker Node
  • kubelet
  • kube-proxy
  • containerd (컨테이너 런타임)
  • 서비스 파드 (Next.js, Spring Boot)
  • 모니터링 파드 (Prometheus, Grafana, Loki)
  • 로깅 파드 (Fluent Bit)

• CNI 플러그인: Calico (Pod 간 통신 및 네트워크 정책 관리)
• LoadBalancer: MetalLB를 통한 온프레미스 환경 내 로드밸런서 구성
• Service 타입: LoadBalancer, ClusterIP 혼합 사용

• Deployment
  • Next.js, Spring Boot, Prometheus, Grafana, Loki를 각각 Deployment로 배포
  • 기본 Replica 수 2개 (Next.js, Spring Boot), 모니터링 계열은 1개
• DaemonSet
  • Fluent Bit을 DaemonSet으로 배포하여 모든 노드에 1개씩 설치
• GitOps (ArgoCD)
  • 모든 서비스는 Git 저장소를 기준으로 선언형(Declarative)으로 관리
  • ArgoCD를 통해 클러스터 상태를 Git 저장소 상태와 동기화

• Horizontal Pod Autoscaler(HPA) 적용
  • CPU 사용률 50% 이상 초과 시 Pod 추가 생성
  • Metrics Server를 통해 실시간 리소스 사용량 수집
• Deployment 설정
  • Rolling Update 방식으로 무중단 배포
  • 설정 예시: maxSurge=1, maxUnavailable=1

• Self-healing
  • 파드 장애 발생 시 ReplicaSet이 자동으로 새로운 파드를 생성하여 복구
• 노드 장애 대응
  • 노드 장애 발생 시 스케줄러가 다른 노드에 파드를 재배치
• 모니터링 및 로깅
  • Prometheus로 메트릭 수집
  • Grafana로 대시보드 구성
  • Loki+Fluent Bit으로 로그 수집 및 중앙 집중화

• Helm Chart
  • 기존 Docker Compose 기반 서비스를 Helm Chart로 변환하여 패키징
  • 환경 별(Dev/Stage/Prod)로 values.yaml을 분리하여 일관성 확보
• Kustomize
  • 환경 별 오버레이 관리(예: dev, prod 설정 분리)

항목	내용
Kubernetes 버전	1.29.x
클러스터 네트워크 범위	192.168.0.0/16
Pod CIDR 설정	--pod-network-cidr=192.168.0.0/16
API Server 포트	6443
MetalLB Address Pool	192.168.1.240-192.168.1.250
Fluent Bit	DaemonSet 배포 (모든 노드 적용)