KubeLLM-Ops — Kubernetes LLM 서빙 운영

<aside> 🚧

진행 중 프로젝트

Kubernetes 기반에서 LLM 서빙을 운영하고, 장애·부하·GPU 상태를 관측하는 AI 인프라 포트폴리오입니다.

</aside>

30초 요약

단순히 LLM API를 실행하는 데서 끝내지 않고, 배포 → 상태 확인 → 장애 재현 → 모니터링 → 복구 확인까지 직접 검증하는 프로젝트입니다. 현재 Mock Backend 기반 운영 검증과 Kubernetes 자동복구, Docker GPU 접근까지 완료했고 실제 vLLM 서빙은 진행 중입니다.

아키텍처 한눈에 보기

실선은 실제 실행으로 검증한 경로이고, 점선은 아직 검증하지 않은 경로입니다.

flowchart LR
    C["Client<br>/v1/chat/completions"] --> G["FastAPI Gateway<br>Docker · kind 2 replicas"]
    G --> MB["Mock Backend<br>VERIFIED"]
    G -.-> V["vLLM<br>Qwen2.5-0.5B-Instruct<br>진행 중"]
    G -->|"/metrics"| P["Prometheus"]
    P --> GF["Grafana<br>Request Rate · P95 · Error Rate"]
    GPU["RTX 4060"] -.->|"DCGM Exporter<br>NOT VERIFIED"| P
    V -.-> GPU

STAR 요약

S · Situation

LLM API를 단순 실행하는 것만으로는 실제 AI 인프라 운영 역량을 보여주기 어려웠습니다. 배포 이후의 상태 확인, 장애 재현, 모니터링과 복구까지 직접 검증할 수 있는 환경이 필요했습니다.

T · Task

FastAPI Gateway와 LLM Backend를 컨테이너·Kubernetes 환경에서 운영하고, 정상/장애 상황을 재현해 관측 가능한 지표와 복구 근거를 남기는 것을 과제로 정했습니다. GPU/vLLM 영역은 실제 실행이 확인된 범위만 완료로 표시하기로 했습니다.

A · Action ⭐

Docker Compose로 Gateway · Mock Backend · Prometheus · Grafana 스택을 구성하고 docker compose ps와 /v1/chat/completions 요청으로 E2E 동작을 확인했습니다.
docker compose stop mock-backend로 Backend 장애를 직접 주입하고, 502 응답과 gateway_requests_error_total, gateway_backend_failures_total{reason="connection_error"} 변화를 Prometheus/Grafana에서 대조했습니다.
Docker Desktop의 kind 클러스터에 Namespace · ConfigMap · Deployment · Service를 배포하고, Startup/Readiness/Liveness Probe 및 Service DNS 기반 통신을 검증했습니다.
Gateway Pod를 강제로 삭제한 뒤 새 Pod 생성 → Ready → API 정상 응답까지 확인해 자동복구 시간을 측정했습니다.
docker run --gpus all ... nvidia-smi로 컨테이너 내부 RTX 4060 접근을 확인하고, vLLM 실행 실패를 GPU 인식 문제가 아닌 CUDA 요구조건과 호스트 Driver 버전 불일치로 분리해 원인을 좁혔습니다.

R · Result

Docker 정상 트래픽과 장애 구간을 실제 metrics로 기록했고, 장애 시점 204건 중 성공 203건 · 502 오류 1건이 일치함을 확인했습니다.
Kubernetes Gateway Pod 삭제 후 약 9초 내 Ready 복구와 API 정상 응답을 확인했습니다.