클라우드 6단계: Kubernetes 기반 배포 자동화 - 100-hours-a-week/16-Hot6-wiki GitHub Wiki

상위 문서: 클라우드 위키
관련 문서: 클라우드 WHY? 문서

Kubernetes 기반 배포 자동화

개요

서비스가 성장하고 인프라가 복잡해짐에 따라, 기존 kubeadm 기반의 수동 오케스트레이션은 유지보수와 장애 대응 측면에서 한계를 드러냈습니다. 특히 etcd 장애 발생 시 전체 클러스터의 운영이 중단되고, 복구 과정에서 과도한 수작업이 요구되는 점은 실제 운영 안정성에 큰 리스크로 작용하였습니다.

이 문서는 현재 운영 중인 FastAPI 기반 AI 서비스의 인프라 아키텍처를 Kubernetes(EKS) 기반으로 전환하고자 한 배경과 목적을 정리한 자료입니다. 기존 kubeadm 구조에서 발생한 문제점을 기술적으로 분석하고, EKS 전환의 필요성을 비용·확장성·자동화·장애 대응 등 다양한 관점에서 설명합니다.

또한 전환 이후의 아키텍처 구조와 각 계층별 구성 요소를 명확히 설명하고, 실제 Kubernetes 리소스 예시와 자동화 전략(HPA, ArgoCD 등)을 포함하여 운영 가능성을 뒷받침합니다.

목차

1. Kubernetes 도입 필요성 결정

왜 Kubernetes를 사용하나요?

현재 서비스 구조 요약

저희의 서비스는 다음과 같은 구조를 기반으로 운영되고 있습니다:

  • 프론트엔드: React 기반 정적 페이지 (S3 + CloudFront)
  • AI 서버: FastAPI 기반 LLM Inference 서버 (GCP VM 기반, Node Affinity 적용)
  • 데이터베이스: MySQL (EC2 또는 Cloud SQL 등에서 운영)
  • 모니터링: Prometheus, Grafana, Loki, Alertmanager
  • 로그/알람 전달: Discord Webhook
  • CI/CD: GitHub Actions + ArgoCD
  • 운영환경 분리: dev, prod 네임스페이스 분리

kubeadm 기반 오케스트레이션의 한계

항목 설명
수동 구성 및 유지보수 부담 인증서 갱신, 업그레이드, 컨트롤 플레인 재설정 등 전부 수작업
장애 복구 어려움 etcd 장애 시 snapshot 및 cert 관리까지 모두 수작업 필요
무중단 배포 전략 부재 Blue-Green 등도 수동으로 라우팅 전환
스토리지 연동 어려움 EBS/EFS 연동이 까다롭고 CSI 설정 직접 구성 필요
모니터링/알람 서비스도 클러스터 의존 클러스터 장애 발생 시 경보 수신 불가능
Multi-AZ 구성의 어려움 고가용성 구성 위해 모든 구성요소 복제 필요
스케일링 어려움 트래픽 폭증 대응을 위해 수동 증설 필요 (HPA/CA 직접 구성)

실질적 장애 복구 사례

  • etcd Pod crash → 클러스터 전체 작동 중단
  • 복구를 위해 수동으로 snapshot을 이용한 etcd 복원, 인증서 재배포 필요
etcdctl snapshot restore /var/lib/etcd/snapshot.db \
  --data-dir /var/lib/etcd-from-backup
  • kubeadm init 재시도 및 CA 키 복원 등 운영자가 모든 구성 책임

왜 EKS로 전환하는가?

1. 운영 복잡도와 장애 대응의 한계

  • kubeadm 기반 클러스터는 모든 Control Plane 구성 요소를 수동으로 관리해야 합니다. 특히 etcd 장애 시, snapshot 복원, CA 인증서 배포, kubeadm 재설정 등 운영자 수작업 부담이 매우 큽니다.

  • 예를 들어, 단일 Control Plane 노드에서 etcd가 크래시하면 클러스터 전체가 정지되고, 다음과 같은 복구 절차가 필요합니다:

    etcdctl snapshot restore /var/lib/etcd/snapshot.db \
  --data-dir /var/lib/etcd-from-backup

  • 복구에는 여러 단계의 명령어와 설정 파일이 필요하며, 서비스는 일시 중지될 수 있어도 운영자가 복구에 몰입해야 하기 때문에 자원이 잠식되고 복원 시간도 예측하기 어렵습니다.

  • 반면, EKS에서는 Control Plane을 AWS가 관리하며, 장애 발생 시 자동으로 감지 및 복구됩니다.
    → Control Plane의 복원 책임이 사라짐으로써, 운영 부담과 위험이 크게 줄어듭니다.

2. 서비스 구성의 복잡도 증가

  • 단순한 단일 서버 아키텍처를 넘어서, 이제는 AI 모델 서버, 프론트엔드 정적 파일, 이미지 업로드 저장소 등 다양한 구성 요소가 클러스터 안팎에서 혼합 운영되고 있습니다.
  • Kubernetes의 네임스페이스 분리, Service Discovery, RBAC, ConfigMap/Secret 기반 구성은 이런 복잡성을 효과적으로 제어할 수 있는 구조입니다.

3. 고급 배포 전략 요구

  • AI 서버는 실험적 기능이 자주 교체되고, 모델도 잦은 테스트가 필요합니다.
  • EKS는 ArgoCD + Argo Rollouts를 이용하여 Canary, Blue-Green, Progressive Delivery 같은 배포 전략을 쉽게 구현할 수 있으며, 빠른 롤백도 가능합니다.

4. 자동화된 복구 및 확장성 확보

  • AI 서버는 특정 시간대에 사용자 요청이 집중되는 패턴이 존재합니다.
  • EKS에서는 다음 기능을 통해 트래픽 변화에 유연하게 대응할 수 있습니다:
    • HPA (Horizontal Pod Autoscaler): CPU/메모리 기반 Pod 수 자동 조절
    • Managed Node Group: EC2 노드 자동 생성/삭제
    • Cluster Autoscaler: 전체 노드 규모 확장
  • 모든 확장·복구 기능이 Kubernetes 내부에서 자동으로 수행되며, Control Plane 상태와 무관하게 안정성을 유지할 수 있습니다.

5. 스토리지 연동 및 관리 효율화

  • 동적 볼륨 프로비저닝을 통해, PVC가 EBS/EFS와 자동 연결되며, 데이터 저장소나 이미지 업로드에도 효율적입니다.
  • StatefulSet + PVC 구성도 완전하게 지원되어 데이터 내구성이 확보됩니다.

6. 클라우드 네이티브 통합

  • EKS는 AWS 서비스와의 연동이 용이합니다:
    • IAM 기반의 Pod 권한 제어
    • ACM을 통한 HTTPS 설정 자동화
    • CloudWatch Logs 및 Metrics 연동
    • Route 53 도메인, ALB 자동 생성 등
  • 이를 통해 네트워크, 보안, 로깅, DNS, 인증서, 확장성까지 모두 통합 운영할 수 있습니다.

2. Kubernetes 아키텍처 다이어그램

image

  • EKS (AWS): 관리형 Control Plane, EC2 기반 Worker Node
  • GCP: Compute Engine 기반 AI 서버 3대
  • S3 + CloudFront: 프론트엔드 정적 자산 및 유저 이미지
  • CI/CD: GitHub Actions → ArgoCD
  • VPN: WireGuard
  • 모니터링/로깅: Prometheus, Grafana, Loki
  • 알람: Alertmanager → Discord

3. 설계 설명 및 타당성 보고서

인프라 계층별 요약

계층 구성 요소
FE React 정적 자산 (S3 + CloudFront)
AI FastAPI 서버 (GCP GCE)
CD GitHub Actions + ArgoCD
인프라 EKS, VPC, LoadBalancer, GCE, Route53
보안 WireGuard VPN
모니터링 Prometheus + Grafana + Loki + Alertmanager

장애 대응 흐름 변화

항목 kubeadm (기존) EKS (전환 후)
Control Plane 복구 직접 snapshot/인증서 복원 AWS 자동 복구
Alertmanager 클러스터 장애 시 함께 다운 별도 관리 인프라 또는 MSA 분리
로그 확인 노드 접속 후 수동 확인 CloudWatch or Loki를 통한 지속 확인
배포 오류 대응 rollback 불가 → 재배포 ArgoCD 및 GitOps 기반 자동 rollback 가능

4. Kubernetes 리소스 명세서

AI 서버 Deployment 예시

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ai-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: ai
  template:
    metadata:
      labels:
        app: ai
    spec:
      containers:
        - name: ai
          image: ghcr.io/yourorg/ai-server:latest
          ports:
            - containerPort: 8000
          env:
            - name: MODEL_PATH
              value: "/models/gemma"

HPA 예시

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: ai-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: ai-server
  minReplicas: 2
  maxReplicas: 8
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 60

5. 아키텍처 구성 요약

EKS (AWS)

  • Control Plane: AWS 관리형
  • Worker Node: EC2 기반, 3개 AZ 분산 구성
  • Load Balancer: ALB (Ingress Controller)
  • DNS: Route53 + ACM
  • CI/CD: GitHub Actions → ArgoCD
  • 모니터링: CloudWatch + Prometheus + Grafana
  • 로깅: Loki
  • 알람: Alertmanager → Discord Webhook

AI 서버 (GCP)

  • Compute Engine: AI 모델 인퍼런스 서버 3대
  • 서비스: FastAPI 기반
  • 연동 방식: WireGuard VPN + 인증

기타 요소

  • 정적 자산: S3 → CloudFront
    • frontend/prod/blue, frontend/prod/green, frontend/dev 구조
  • 이미지 업로드:
    • /assets/temp/uuid... → CNN 검증 후 /assets/images/uuid... 이동
  • 보안: WireGuard VPN 기반 내부 통신

6. 애플리케이션 구조 (Namespace 별 구성)

서비스 복잡도가 증가함에 따라 네임스페이스 단위로 애플리케이션을 구성하였습니다. 이를 통해 운영환경 분리(dev/prod), 자원 관리, RBAC 제어, 모니터링 라벨링 등을 명확히 할 수 있습니다.

네임스페이스 구성

네임스페이스 역할
dev 개발 및 테스트용 환경. CI/CD 자동화 배포의 기본 대상
prod 운영 환경. 안정성, 알림, 롤백 전략이 강화된 환경
monitoring Prometheus, Grafana, Loki, Alertmanager 배포
argo ArgoCD 및 Rollouts 운영
shared 공용 인프라(VPN, 외부 서비스 연동 등) 구성 시 사용 가능

앱 배포 구조 예시

dev/
├── ai-server/
│   ├── deployment.yaml
│   ├── service.yaml
│   └── hpa.yaml
├── fe-proxy/
│   ├── deployment.yaml
│   └── service.yaml

prod/
├── ai-server/
│   ├── deployment.yaml
│   ├── rollout.yaml
│   └── hpa.yaml
├── fe-proxy/
│   ├── deployment.yaml
│   └── service.yaml

운영 환경에는 Deployment 대신 Rollout을 사용하고, Argo Rollouts CRD를 기반으로 Canary/Blue-Green을 수행합니다.

7. CI/CD 및 배포 흐름도

서비스는 GitHub Actions 기반 CI와 ArgoCD 기반 CD 구조를 따릅니다.
또한 운영환경(prod)은 Blue-Green 방식의 무중단 배포를 지원합니다.

전체 배포 흐름

Dev 환경 배포 흐름

graph TD
    A[개발자가 Pull Request 생성] --> B[CI 실행: GitHub Actions]
    B --> C[테스트, Lint, Build Docker Image]
    C --> D[DockerHub에 이미지 Push]
    D --> E[GitOps 배포 파일 갱신]
    E --> F[ArgoCD 감지 → 배포 시작]
    F --> G[dev 네임스페이스에 자동 배포]

운영 환경 배포 흐름

graph TD
    H[main 브랜치 병합] --> I[Argo Rollouts Blue-Green 시작]
    I --> J[신규 버전 배포 완료]
    J --> K[Prometheus 기반 분석 + 테스트 요청]
    K --> L{성공 여부}
    L -- 성공 --> M[트래픽 100% → Green, 기존 Blue 제거]
    L -- 실패 --> N[트래픽 유지 → 기존 Blue 지속 운영]

CI 예시 스크립트 (FastAPI)

name: AI CI

on:
  push:
    branches: [main, dev]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - run: pip install -r requirements.txt
      - run: |
          docker build -t ghcr.io/myorg/ai-server:${{ github.sha }} .
          docker push ghcr.io/myorg/ai-server:${{ github.sha }}

CD 예시 디렉터리 (GitOps 구조)

k8s/
├── dev/
│   └── ai-server/
│       └── deployment.yaml
├── prod/
│   └── ai-server/
│       └── rollout.yaml

Argo Rollouts 예시

apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata:
  name: ai-server
spec:
  replicas: 2
  strategy:
    canary:
      steps:
        - setWeight: 30
        - pause: { duration: 60s }
        - setWeight: 100
  selector:
    matchLabels:
      app: ai-server
  template:
    metadata:
      labels:
        app: ai-server
    spec:
      containers:
        - name: ai-server
          image: ghcr.io/myorg/ai-server:1.2.0

실패 시 자동으로 이전 버전으로 복원되고, Discord Webhook으로 결과 알림이 전송됩니다.

8. 비용 산정

기준 가정

  • 리전: ap-northeast-2 (서울)
  • EC2 인스턴스 요금:
    • t3.medium: 약 $0.0416/시간
    • t3.large: 약 $0.0832/시간
    • t3.small: 약 $0.0208/시간
  • 월 사용 시간: 720시간
  • EBS SSD 스토리지: 약 $0.114/GB/월 (gp3 기준)
  • ALB: 약 $18~30/월
  • ArgoCD, Prometheus, Grafana, Loki, Alertmanager는 경량 단일 Pod로 가정
  • GCP Compute Engine은 e2-medium 기준 사용

개발 환경 (Dev)

구성 요소 인스턴스 타입 개수 예상 비용 (USD) 설명
EC2 (ArgoCD, VPN 등) t3.small 1 ~$15 WireGuard + ArgoCD 운영
EC2 (모니터링 전용) t3.medium 1 ~$30 Prometheus, Grafana, Loki 등
EBS 스토리지 30GB 1 ~$3.5 기본 모니터링 데이터 저장
DockerHub 사용량 - - $0~10 요금제에 따라 다름 (Free~Pro)
합계 - - $50~60/월

운영 환경 (Prod)

구성 요소 인스턴스 타입 개수 예상 비용 (USD) 설명
EKS Control Plane 관리형 1 무료 AWS 기본 제공
Worker Node (3AZ) t3.large 3 ~$180 GCP와 통신 포함 인퍼런스 백엔드
모니터링/알람 서버 t3.medium 1 ~$30 Alertmanager, Loki 등
Redis/Kafka 클러스터 t3.medium 3 ~$90 EKS 내부의 상태 저장형 구성
GCP AI 서버 e2-medium 3 ~$93 Compute Engine, 외부 서비스로 구성
EBS 스토리지 100GB 3 ~$34 고가용성 위한 분산 디스크 구성
ALB (Ingress) - 1 ~$25 ALB + ACM 인증서 포함
S3 + CloudFront - - $5~15 정적 파일 호스팅 + 캐시
Discord Webhook - - 무료 알림 전송
합계 - - $470~500/월

요약 비교

항목 Dev 환경 Prod 환경
월 예상 비용 $50~60 $470~500
운영 대상 테스트/운영도구 전체 서비스
구성 복잡도 단일 노드/경량 EKS + GCP + AZ 3중화
확장성/모니터링 제한적 완전 구성
배포 전략 CI 기반 단순 배포 Argo Rollouts 활용

참고사항

  • GCP 측 비용은 정기 청구 기준으로 환율 변동 및 크레딧 적용 여부에 따라 달라질 수 있습니다.
  • Spot 인스턴스를 적용하면 최대 50% 이상 절감 가능하나, AI 서버와 Kafka/Redis에는 비추천됩니다.
  • 알람 시스템은 Discord Webhook으로 연동되어 별도 비용 없음.
  • ArgoCD, Loki, Grafana 등은 모두 오픈소스이므로 라이선스 비용 없음.