Inference Gateway 배포 가이드
이 문서는 kgateway + Bifrost 기반 추론 게이트웨이의 실전 배포 절차를 다룹니다. 아키텍처 개념과 라우팅 전략(Cascade, Semantic Router, 2-Tier 구조)은 추론 게이트웨이 라우팅을 참조하세요.
이 가이드는 3개 문서로 구성됩니다. 순차적으로 학습하거나, 필요한 섹션만 선택하여 참조하세요.
프로덕션 추론 파이프라인 참조 아키텍처
EKS 기반 프로덕션 추론 파이프라인의 전체 요청 흐름입니다. CloudFront(WAF/Shield) → NLB → kgateway가 진입 트래픽을 받고, 이후 두 가지 라우팅 경로를 목적에 따라 선택해 구성합니다.
- L1 — across-model 프록시 / 거버넌스: Bifrost(또는 LLM Classifier)로 외부/내부 모델 추상화, cascade, 비용 추적, semantic cache. "어느 모델인가"를 결정합니다. → 기본 배포 · 고급 기능
- L2 — within-model KV-aware 라우팅: Gateway API Inference Extension(InferencePool + EPP)으로 vLLM 메트릭(KV cache·부하) 기반 Pod 선택. "어느 Pod인가"를 결정합니다. → 고급 기능: Inference Extension
두 레이어는 배타적이지 않으며 함께 쓸 수 있습니다(L1 → L2 → vLLM). 레이어 정의와 선택 기준은 라우팅 전략을 참조하세요.
아래 다이어그램은 L1(Bifrost)·L2(llm-d EPP)·관측성을 모두 포함한 목표(reference) 아키텍처입니다. 실제 배포는 위 두 경로를 선택·조합하며, KV-aware(L2)가 필요한 경우 Inference Extension 섹션의 InferencePool + EPP 절차를 따릅니다.
배포 단계 개요
기본 배포 (필수)
단일 NLB 엔드포인트 뒤에서 kgateway + HTTPRoute + Bifrost를 구성하여 기본 추론 파이프라인을 완성합니다.
포함 내용:
- kgateway 설치 및 Gateway API CRD 구성
- GatewayClass, Gateway, HTTPRoute 리소스 정의
- ReferenceGrant를 통한 크로스 네임스페이스 접근
- Bifrost Gateway Mode 구성 (config.json + PVC)
- provider/model 포맷 및 IDE 호환성 (Aider, Cline, Continue.dev)
- SQLite 초기화 절차 (config.json 변경 시)
학습 시간: 30분 | 배포 시간: 45분
고급 기능 (선택)
프롬프트 기반 자동 라우팅, 프로덕션 보안 레이어, Semantic Caching을 추가하여 비용 최적화와 보안을 강화합니다.
포함 내용:
- LLM Classifier 배포 (프롬프트 기반 SLM/LLM 자동 분기)
- Gateway API Inference Extension (InferencePool + EPP) — KV-aware(L2) 라우팅
- CloudFront + WAF/Shield 보안 레이어
- Semantic Caching 구현 옵션 (GPTCache, RedisVL, Portkey, Helicone)
학습 시간: 45분 | 배포 시간: 60-90분
트러블슈팅 (참조)
배포 및 운영 중 발생하는 일반적인 문제와 해결 방법을 다룹니다.
포함 내용:
- 404 Not Found (HTTPRoute/Gateway 설정 오류)
- Bifrost provider/model 에러
- Bifrost 모델명 정규화 문제
- Langfuse Sub-path 404
- OTel Trace 미도착
참조 빈도: 배포 시 또는 문 제 발생 시
학습 경로
빠른 시작 (개발/테스트 환경)
소요 시간: 1-2시간
프로덕션 구성 (완전한 파이프라인)
소요 시간: 3-4시간
사전 준비 사항
모든 배포 단계를 진행하기 전에 다음을 확인하세요.
필수 요구 사항
- EKS 클러스터 (K8s 1.33+ 권장. DRA(Dynamic Resource Allocation)는 K8s 1.34에서 GA)
- kubectl 설치 및 클러스터 접근 권한
- Helm 3.x 설치
- vLLM 또는 llm-d 기반 모델 서빙 Pod 배포 완료
권장 사항
- AWS Load Balancer Controller 설치 (NLB 자동 생성)
- Langfuse 배포 완료 (Langfuse 배포 가이드 참조)
- 프로덕션 환경: ACM 인증서 발급 (CloudFront + TLS용)
다음 단계
- 시작하기: 기본 배포로 이동하여 kgateway 설치를 시작하세요.
- 아키텍처 이해: 배포 전 추론 게이트웨이 라우팅을 읽고 전체 구조를 파악하세요.
- 모니터링 준비: Langfuse 배포 가이드를 참조하여 관측성 스택을 구성하세요.
참고 자료
- 추론 게이트웨이 라우팅 - kgateway 아키텍처 및 라우팅 전략 상세
- Langfuse 배포 가이드 - Helm 설치, OTel 연동, Redis/ClickHouse 구성
- Agent 모니터링 - Langfuse 아키텍처 및 컴포넌트
- Kubernetes Gateway API 공식 문서
- kgateway 공식 문서
- Bifrost 공식 문서