Kubeadm - 100-hours-a-week/9-team-Devths-WIKI GitHub Wiki

Devths 서비스는 개인 포트폴리오 기반 채용 플랫폼으로 커뮤니티, 채팅, AI 챗봇, 캘린더 기능을 포함한 다수의 서비스로 구성됨.

초기에는 Docker 기반 서비스와 AWS Auto Scaling Group을 활용하여 인스턴스 단위 확장을 수행하는 구조(V2)로 운영함.

그러나 실시간 채팅과 AI 추론이 결합된 서비스 특성상 트래픽 스파이크 대응, 배포 안정성, 리소스 효율성 측면에서 인프라 구조적 한계가 발생함.

이를 해결하기 위해 컨테이너 단위 오케스트레이션 시스템인 Kubernetes를 도입하고, kubeadm 기반 클러스터를 직접 구축하여 서비스 확장성과 운영 안정성을 확보하는 것을 목표로 함.

기존 인프라는 다음과 같은 구조로 운영됨.

• Frontend (Next.js)
• Backend API (Spring Boot)
• Chat Server (WebSocket)
• AI API (FastAPI /)

각 서비스는 독립적인 EC2 Auto Scaling Group으로 운영되어 트래픽 증가 시 인스턴스 단위 확장을 수행함.

하지만 이 구조는 다음과 같은 한계를 가지게 됨.

VM 단위 확장의 구조적 지연

Auto Scaling Group을 통한 확장은 EC2 인스턴스 생성 → OS 부팅 → 애플리케이션 실행까지 최소 3~5분이 소요됨.

실시간 트래픽 스파이크 상황에서는 즉각적인 확장이 불가능하여 서비스 지연이나 장애로 이어질 가능성이 높음.

비효율적인 자원 확장

AI 서비스는 평시 메모리 사용량이 80% 이상을 차지하는 메모리 집약적 워크로드임.

컨테이너 하나를 추가해야 하는 상황에서도 전체 EC2 인스턴스를 생성해야 하므로 비용과 자원 효율이 크게 저하됨.

배포 시 연결 단절 문제

기존 방식에서는 인스턴스 교체나 컨테이너 재시작 과정에서 기존 연결이 종료됨.

특히 WebSocket 기반 채팅이나 AI 스트리밍 응답의 경우 배포 시 사용자 연결이 끊어지는 문제가 발생함.

이러한 문제는 서비스 성장 이후 운영 안정성에 직접적인 영향을 주기 때문에, 컨테이너 단위 자동 복구와 초단위 확장이 가능한 오케스트레이션 시스템이 필요함.

Devths 인프라는 다음과 같은 가설을 기반으로 Kubernetes 도입을 설계함.

가설 1. 컨테이너 단위 초단위 스케일링

VM 확장이 아닌 Pod 단위 확장(HPA) 을 적용함.

이미 확보된 워커 노드 자원을 활용하여 초단위로 파드를 복제함으로써 트래픽 스파이크를 즉각적으로 방어할 수 있음.

가설 2. 메모리 집약적 워크로드의 안정적 복구

AI 서비스에 Resource Request와 Limit을 설정하여 메모리 사용량을 통제함.

OOM 발생 시 전체 인스턴스가 다운되는 것이 아니라 해당 파드만 재시작(Self-Healing) 되도록 설계함.

이를 통해 장애 복구 시간을 크게 단축할 수 있음.

가설 3. 무중단 배포 구현

Readiness Probe를 활용하여 새 버전 파드가 완전히 준비된 후 트래픽을 전환함.

이를 통해 배포 과정에서 WebSocket 연결 단절이나 스트리밍 중단을 방지함.

결과적으로 Kubernetes 도입을 통해 다음과 같은 효과를 기대함.

• 초단위 확장 가능한 서비스 구조 확보
• 장애 발생 시 자동 복구(Self-Healing)
• 무중단 롤링 배포
• 리소스 단위 확장으로 비용 효율 향상

Kubernetes 도입 과정에서 ECS, EKS, kubeadm 기반 Kubernetes를 비교 검토함.

ECS 대비 Kubernetes 선택

ECS는 AWS에 종속되는 구조로 멀티 클라우드나 온프레미스 확장성이 제한됨.

반면 Kubernetes는 글로벌 오픈소스 표준으로 다양한 인프라 환경에서 동일한 운영 모델을 유지할 수 있음.

EKS 대비 kubeadm 선택

EKS는 관리형 Kubernetes 서비스로 운영 부담이 적다는 장점이 있음.

하지만 Control Plane 내부 동작이 블랙박스 형태로 제공되어 네트워크 정책이나 클러스터 구성의 세밀한 제어가 어려움.

Devths 서비스는 다음과 같은 이유로 kubeadm 기반 클러스터를 선택함.

• 네트워크 정책(L3/L4) 세밀 제어 필요
• CNI 및 클러스터 네트워크 커스터마이징 필요
• 인프라 운영 구조를 직접 제어하여 기술 이해도 확보

따라서 운영 복잡성을 감수하더라도 인프라 주도권 확보를 위해 kubeadm 기반 Kubernetes 클러스터를 구축하는 전략을 채택함.

외부 트래픽은 NLB를 통해 유입되고, NodePort를 통해 Gateway API 컨트롤러로 전달됨.

이후 Gateway의 라우팅 정책에 따라 각 서비스의 ClusterIP Service로 분기되고, 최종적으로 파드에 연결됨. 파드 간 통신은 Calico CNI가 담당함.

Devths는 prod와 nonprod를 분리한 2개 클러스터 전략으로 설계함. nonprod는 기능 검증, 장애 재현, 배포 테스트, 인프라 실험을 위한 환경이고, prod는 실사용자 트래픽을 처리하는 안정성 중심 환경임.

prod에서는 Stateless 서비스만 Kubernetes 내부에 배치하고, PostgreSQL은 RDS, Redis는 ElastiCache, 메시지 큐와 Vector DB도 고가용성 서비스로 분리함.

이는 핵심 데이터 계층을 애플리케이션 클러스터 장애와 분리해 운영 리스크를 낮추기 위함임.

이 구조에서 Kubernetes는 애플리케이션 실행, 확장, 배포, 복구를 담당하고, 데이터 계층은 내구성과 백업 체계가 확보된 외부 서비스가 담당함.

초기 prod 기준 권장 토폴로지는 다음과 같음.

AI 워크로드는 메모리 사용량이 크고 일반 API와 자원 충돌 가능성이 높으므로 전용 워커 또는 taint/toleration 기반 분리를 권장함.

nonprod에서는 애플리케이션뿐 아니라 Statefull한 컴포넌트도 클러스터 내부에 배치함.

DB까지 Pod + PV/PVC로 올려서 서비스 간 통합 테스트와 장애 복구 실험을 빠르게 할 수 있도록 구성함. 스토리지는 EBS 기반 동적 프로비저닝을 사용해 테스트 환경에서 필요한 볼륨을 유연하게 생성하도록 설계함.

이 환경은 비용 절감과 실험성이 우선이며, 운영 환경 수준의 고가용성을 보장하는 구조로 보지는 않음. 즉, 데이터 영속성보다 빠른 재현성과 환경 독립성이 더 중요한 클러스터임.

Devths 서비스 특성:

• Chat Server: SSE 기반 단방향 스트리밍
• AI API: SSE 기반 스트리밍 응답
• Backend: 일반 REST API
• Frontend: 정적 자산 + API 프록시
• 팀 규모: 2~5인 소규모
• 환경: kubeadm + AWS

트래픽 특성:

• SSE 연결이 전체 연결의 상당 비중 차지
• 장시간 연결 (AI 스트리밍 최대 수분)
• 연결 수 > 초당 요청 수 패턴

계층 1: 외부 진입 (AWS NLB)

계층 2: 클러스터 진입 (NodePort)

계층 3: L7 라우팅 (Gateway API 구현체)

계층 4: Pod 간 통신 (CNI)

계층 5: 정책 제어 (NetworkPolicy)

계층 6: 관측 (Observability)

선택지 비교

NLB 선택 근거

근거 1: SSE idle timeout 문제

ALB의 기본 idle timeout은 60초. SSE는 서버가 데이터를 보내지 않는 구간이 생길 수 있는데, 이 구간이 60초를 넘으면 ALB가 연결을 강제 종료.

ALB 최대 설정값: 4000초 그러나 이 값은 모든 연결에 전역 적용됨 → REST API 연결도 4000초까지 유지 → 불필요한 연결 점유 → 서비스별 timeout 분리 불가

NLB는 TCP 레벨에서 동작하므로 idle timeout 개념 자체가 없음. 따라서 SSE 연결이 살아있는 한 끊지 않음.

근거 2: kubeadm 환경에서 ALB 연동 복잡도

ALB Ingress Controller 방식은 AWS Load Balancer Controller 설치가 필요합니다.

ALB 사용 시 필요한 추가 작업: 1. AWS Load Balancer Controller 설치 2. IAM OIDC Provider 설정 (kubeadm은 EKS와 달리 수동) 3. IRSA(IAM Roles for Service Accounts) 수동 구성 4. ServiceAccount에 IAM Role Annotation 추가

NLB + NodePort 사용 시: 1. NodePort Service 정의 → 끝

소규모팀에서 컴포넌트가 적을수록 장애 발생 시 원인 추적이 단순해짐.

근거 3: L7 라우팅은 Gateway API가 담당

ALB의 핵심 장점인 경로 기반 라우팅은 이미 Gateway API가 담당. ALB의 L7 기능을 중복으로 사용할 이유가 없음

결론: NLB 선택

기존 초안의 nginx ingress controller는 최신 설계 기준에서는 기본 축으로 두기 어려움. ingress-nginx는 2026년 3월 은퇴 예정이므로, 신규 설계는 Gateway API 중심으로 설계함.

또한,Gateway API는 Kubernetes 공식 차세대 네트워킹 모델로 정리되어 있으며, Ingress에 비해서 더 명확한 역할 분리와 고급 라우팅 구성을 제공함. (Kubernetes)

따라서 외부 진입 구조는 NLB → NodePort → Gateway API → Service → Pod 로 정의함.

Gateway API 구현체 비교

Nginx GW Fabric 선택 근거

근거 1: Gateway API 스펙 완전 준수

현재 Cilium Gateway API는 URLRewrite, RequestMirror, BackendTLSPolicy 등 Extended 기능이 미구현 상태. Nginx Gateway Fabric은 Gateway API v1.1 기준 Core/Extended 기능을 완전히 준수. 현재 당장 필요하지 않더라도 향후 서비스 간 mTLS 도입, 트래픽 미러링(Prod) 등 확장 시 재설계 없이 대응 가능.

근거 2: Envoy Gateway 대비 운영 레퍼런스

Envoy Gateway는 2023년 시작된 프로젝트입니다. SSE 관련 트러블슈팅 레퍼런스가 거의 없습니다. Nginx는 수년간 SSE 설정 사례가 축적되어 있어 장애 시 참고 자료 접근성이 압도적으로 높습니다.

근거 3: 구성 단순도

Nginx Gateway Fabric 구성:
  nginx-gateway (Controller) — 1개 Pod
  nginx (데이터 플레인)       — NodePort로 외부 노출
	=> 두 종류의 Pod만 관리

Envoy Gateway 구성:
  envoy-gateway (Controller)
  envoy (데이터 플레인)
  + EnvoyProxy CRD 별도 관리
  → 구성 파일 복잡도 높음
  
Kong 구성:
	플러그인 관리를 위해 KongPlugin CRD와 HTTPRoute 어노테이션 혼용.
	표준 Gateway API 미충족

근거 4: 운영 친숙도와 디버깅 접근성

Nginx 기반 운영 경험이 있다면 디버깅 방법을 별도 학습 없이 즉시 적용 가능. 장애 발생 시 nginx-gateway 로그로 설정 반영 여부를 확인하고, nginx -T 명령으로 현재 적용된 설정을 직접 확인. Envoy Gateway는 xDS 프로토콜과 Envoy 설정 구조(Listener/Cluster/Route) 학습이 선행 필요.

파드 간 네트워크는 Calico를 사용함. Calico는 Kubernetes에서 널리 사용되는 CNI로, 안정적인 L3 네트워킹과 NetworkPolicy 기반 서비스 간 통신 제어 기능을 제공함.

Devths 서비스는 프런트엔드, 백엔드, AI 서버가 서로 API 호출을 수행하는 구조이므로 서비스 간 네트워크 접근을 명확히 제한할 필요가 있음. Calico의 NetworkPolicy를 통해 프런트엔드는 백엔드만 접근 가능하도록 제한하고, AI 서버는 백엔드 API를 통해서만 호출되도록 정책을 구성함. 이를 통해 내부 서비스 간 불필요한 접근을 차단하고 보안 경계를 형성함.

또한 본 클러스터는 클라우드 환경에서 kubeadm 기반으로 구축되므로, 별도의 복잡한 네트워크 구성 없이 Calico IPIP 기반 오버레이 네트워크를 사용하여 노드 간 파드 통신을 구성함. 이를 통해 클라우드 환경에서도 안정적인 파드 네트워크를 구성할 수 있음.

CNI 비교

Calico 선택 근거

근거 1: CNI 역할 범위와 요구사항 일치

CNI의 핵심 역할은 Pod 간 네트워크 통신과 NetworkPolicy 강제임. 트래픽 가시화, 외부 라우팅, 메트릭 수집은 각각 Hubble, Gateway API, Prometheus가 담당하는 영역임. CNI에 관측 기능까지 요구하는 것은 단일 책임 원칙에서 벗어나며, 해당 기능이 필요하다면 전문 도구를 별도로 도입하는 것이 구조적으로 더 명확함.

Devths에서 요구하는 다음 사항을 안정적으로 충족

• Pod 간 네트워크 통신
• NetworkPolicy 강제 (L3-L4)

근거 2 : L3-L4 NetworkPolicy로 요구사항 완전 충족

Devths의 NetworkPolicy 요구사항을 충족

허용 정책:
  Gateway  → Frontend       IP + Port
  Gateway  → Backend        IP + Port
  Gateway  → Chat           IP + Port
  Gateway  → AI API         IP + Port
  Backend  → Chat           IP + Port
  Backend  → AI API         IP + Port
  Backend  → RDS            IP + Port 5432
  Backend  → ElastiCache    IP + Port 6379
  Chat     → ElastiCache    IP + Port 6379

차단 정책:
  위 허용 목록 외 모든 통신 차단

L7 정책이 필요한 시나리오가 없으며, L7 접근 제어는 이미 Gateway API의 HTTPRoute에서 경로 기반 라우팅으로 처리하고 있으므로 CNI 레벨에서 중복 제어할 이유가 없음.

근거 3: kubeadm 공식 문서 설치 예시가 Calico

Kubernetes 공식 문서의 kubeadm 클러스터 구성 가이드에서 CNI 설치 예시로 Calico를 직접 사용함. → 소규모팀이 참고할 수 있는 레퍼런스 가장 많음

근거 4: AWS 환경 IPIP 모드 운영 레퍼런스 풍부

AWS VPC 환경에서는 BGP 라우팅을 사용할 수 없으므로 Calico는 IPIP 모드로 동작함. IPIP는 AWS VPC 환경에서 수년간 검증된 조합.

Cilium은 AWS EC2 인스턴스의 커널 버전과 인스턴스 유형에 따라 eBPF 지원 범위가 달라질 수 있음. kubeadm + AWS 환경에서의 Cilium 운영 레퍼런스는 EKS 환경에 집중되어 있어 kubeadm 환경에서의 트러블슈팅 사례가 상대적으로 부족.

근거 5: eBPF 성능 이점 — 현재 규모에서 무의미

eBPF 이점이 발생하는 조건:     Devths 현재 규모:
  Service 수 500개 이상    →     약 10개
  노드 수 50개 이상        →     4개 (prod 기준)
  초당 수십만 요청         →     해당 없음

패킷당 처리 오버헤드 차이:
  1000 Service 환경: iptables 300μs vs eBPF 30μs
  10 Service 환경:   iptables 3μs   vs eBPF 2μs
  → 차이 1μs, 측정 및 체감 불가능

현재 규모에서 측정조차 불가능한 성능 이점을 근거로 운영 복잡도와 학습 비용을 추가하는 것은 타당하지 않음. 서비스가 성장 후 Cilium 전환을 검토하는 것이 합리적.

인증서 발급과 갱신은 cert-manager로 자동화함. cert-manager는 Kubernetes 클러스터 내부에서 TLS 인증서를 발급·갱신하는 표준 도구이며, Let’s Encrypt와 연동 가능함.

ALB + ACM을 사용하여 처리하게 된다면, AWS 외부 리소스이므로 벤더 종속적이게 바뀌게 된다. 또한, ALB가 앞단에서 헤더를 변조하거나 미리 처리를 해버리면, Kong의 세밀한 트래픽 제어 기능이나 mTLS(상호 TLS) 같은 고급 보안 기능을 구현할 때 충돌이 발생하거나 설정이 꼬일 수 있음

prod에서는 핵심 DB를 Kubernetes 내부에 올리지 않음. EBS는 단일 AZ 의존성과 노드 제약이 있으므로, 운영 데이터베이스를 직접 쿠버네티스 내부에서 장기 운영하는 것보다 RDS를 사용하는 것이 안정성 측면에서 더 적절함. 따라서 prod에서 PV/PVC는 주로 보조적 상태 저장이나 내부 운영 도구용으로 제한함.

nonprod에서는 자체 Stateful 워크로드를 실험할 수 있도록 PV/PVC 기반 구조를 사용함. EBS StorageClass를 통해 동적 프로비저닝하고, DB Pod는 StatefulSet으로 구성함. 이 환경은 운영 수준의 데이터 보존보다 개발·검증 목적이 우선이므로 스토리지 구조도 단순하고 반복 가능한 방향으로 설계함.

Stateless 서비스는 모두 Deployment로 배포함. ReplicaSet은 Deployment 하위에서 자동 관리되므로 설계 문서에서는 제어 단위를 Deployment로 통일하는 것이 자연스러움. 롤링 업데이트를 적용해 새 파드가 준비된 후 기존 파드를 순차 종료하도록 구성함.

서비스별 확장 기준은 다음과 같이 가져감.

서비스별 확장 기준은 다음과 같이 가져감.

HPA는 기본적으로 metrics-server가 제공하는 CPU, Memory 메트릭을 사용함.

다만 Devths 서비스는 단순 CPU 사용량보다 서비스 특성 기반 확장이 중요한 구조임. 

특히 채팅 서버는 동시 연결 수 증가에 따라 메모리 사용량이 크게 증가하고, Backend API는 요청량에 따라 부하가 급격히 증가할 수 있음.

따라서 Backend API의 RPS, Chat Server의 동시 연결 수와 같은 서비스별 지표는 Prometheus와 Prometheus Adapter를 연계한 Custom Metrics 기반 HPA로 확장하도록 설계함.

HPA는 기본적으로 metrics-server가 제공하는 CPU, Memory 메트릭을 사용함.

다만 Devths 서비스는 단순 CPU 사용량보다 서비스 특성 기반 확장이 중요한 구조임. 

특히 채팅 서버는 동시 연결 수 증가에 따라 메모리 사용량이 크게 증가하고, Backend API는 요청량에 따라 부하가 급격히 증가할 수 있음.

따라서 Backend API의 RPS, Chat Server의 동시 연결 수와 같은 서비스별 지표는 Prometheus와 Prometheus Adapter를 연계한 Custom Metrics 기반 HPA로 확장하도록 설계함.

Devths Pod가 동일한 노드에 무작위로 배치될 경우 자원 경합(Resource Contention)이 발생할 가능성과 SPOF의 가능성이 있음.

이를 방지하기 위해 Kubernetes의 Pod Anti-Affinity를 활용한 워크로드 분리 전략을 적용함. Pod Affinity / Anti-Affinity 설계

Affinity는 스케줄러에게 Pod 배치 위치를 제어하는 설정임. Request/Limit만으로는 한 노드에 특정 Pod가 집중되는 상황을 막을 수 없으므로 Affinity를 함께 설계해야 함.

pod- AntiAffinity (Hard): 같은 종류의 Pod를 반드시 다른 노드에 배치 조건 불만족 시 Pending — 같은 노드 배치보다 Pending이 나음

pod- AntiAffinity (Soft): 가능하면 다른 노드에 배치하되, 불가피한 경우 허용 노드가 부족한 상황에서도 서비스 중단 방지

모든 서비스는 Taint 없이 Worker Node 4대 어디든 스케줄링 가능하도록 구성하고, podAntiAffinity Soft 설정으로 분산 배치를 유도함. PriorityClass는 사용하지 않음. Cluster Autoscaler가 자원 부족 시 노드를 추가하므로 강제 축출이 발생하지 않음.

서비스 별 어피니티 설정

FE

affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
    - weight: 100
      podAffinityTerm:
        labelSelector:
          matchLabels:
            app: frontend
        topologyKey: kubernetes.io/hostname
    - weight: 50
      podAffinityTerm:
        labelSelector:
          matchLabels:
            app: backend-api
        topologyKey: kubernetes.io/hostname

BE

affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
    - weight: 100
      podAffinityTerm:
        labelSelector:
          matchLabels:
            app: frontend
        topologyKey: kubernetes.io/hostname
    - weight: 50
      podAffinityTerm:
        labelSelector:
          matchLabels:
            app: backend-api
        topologyKey: kubernetes.io/hostname

AI

affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
    - weight: 100
      podAffinityTerm:
        labelSelector:
          matchLabels:
            app: ai-api
        topologyKey: kubernetes.io/hostname

HPA max 6이 노드 수(4)를 초과하더라도 Soft 설정이므로 같은 노드에 공존 가능하여 Pending 없이 스케줄링됨.

파드 확장만으로는 스케줄링이 안 되는 상황을 막기 위해 Cluster Autoscaler를 함께 사용함.

최대 확장 시 26개의 애플리케이션 파드가 실행될 수 있으며, Worker Node의 가용 리소스와 파드 리소스 요청량을 고려할 때 최소 4~5개의 노드가 필요함. (개수와 Request를 고려)

kubeadm 환경에서는 Clustr AutoScaler가 노드를 직접 생성하지 못함. 노드 생성 기능은 클라우드 인프라가 담당하고, CA는 ASG의 크기를 조절하는 컨트롤러 역할만 수행함

Argo CD는 클러스터 내부 Pod로 배치하고 GitOps 방식으로 운영함. 모든 배포 정의는 Git 저장소의 Helm Cahrt를 기준으로 관리하고, 클러스터는 해당 상태를 자동 동기화하도록 구성함. 이렇게 하면 수동 배포를 줄이고 변경 이력을 명확히 추적할 수 있음.

7.2.1 Helm Chart

Helm Chart는 Prometheus, Loki, Tempo, Argo CD, External Secrets와 같은 외부 플랫폼 서비스 배포에 사용함. 공식 Chart를 활용하여 설치와 버전 관리를 수행하고, values 파일을 통해 기본 설정만 조정하도록 구성함.

7.2.2 Kustomize

Devths 애플리케이션(Frontend, Backend API, Chat Server, AI API)은 Kustomize 기반 매니페스트로 관리함. 기본 리소스는 base로 정의하고, nonprod와 prod 환경은 overlay를 통해 설정 차이를 분리함.

환경변수와 민감 정보는 Parameter Store와 External Secrets Operator를 연동해 관리함. 즉, Secret 원본은 AWS 측에 두고 Kubernetes에는 필요한 시점에만 동기화함. 이를 통해 Git 저장소에 비밀값을 남기지 않고, 환경별 시크릿도 분리해 관리할 수 있음.

새 이미지가 Git에 반영되면 Argo CD가 변경을 감지하고 Deployment를 갱신함. 새 파드는 readiness가 통과된 뒤에만 트래픽을 받으며, 이후 기존 파드가 순차 종료됨. 따라서 커뮤니티, 캘린더, 채팅 기능을 운영 중인 상태에서도 배포가 가능함.