inference-gateway-routing

name	inference-gateway-routing
description	Configure kgateway v2.0+ as L1 and Bifrost v1.x or LiteLLM v1.60+ as L2 for a 2-Tier Inference Gateway on EKS. Apply Cascade Routing (Haiku→Sonnet→Opus fallback), Semantic Router (intent-based model pick), and HTTPRoute with OTel trace propagation to Langfuse.
argument-hint	[routing pattern, providers, target cost/SLO]
user-invocable	true
model	claude-sonnet-4-6
allowed-tools	Read,Write,Edit,Bash,Grep,Glob,mcp__eks,mcp__aws-documentation,mcp__prometheus

When to Use

• vLLM + 외부 LLM(Bedrock/OpenAI/Anthropic) 을 단일 엔드포인트로 통합할 때
• 비용 절감을 위해 Cascade Routing (경량 모델 우선 → 실패 시 강력 모델) 이 필요할 때
• 의도 분류 기반 Semantic Router 로 모델 자동 선택을 원할 때
• 다중 tenant / multi-project 격리가 필요할 때

When NOT to Use

• 단일 모델·단일 프로바이더 → vLLM OpenAI 호환 엔드포인트 직결로 충분
• MCP/A2A stateful 세션만 처리 → agentgateway 전용 구성 사용
• ingress 수준 TLS 만 필요 → 일반 ALB Ingress 로 충분

Preconditions

• EKS 클러스터에 Kubernetes Gateway API CRD 설치 (gateway-api v1.1+)
• kgateway-system namespace 또는 전용 namespace 준비
• Langfuse / OTel Collector 가 배포되어 있음
• 각 LLM provider API Key 가 Secrets Manager 에 저장

Procedure

Step 1. Gateway API CRD 설치

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml
kubectl get crd | grep gateway.networking.k8s.io

Step 2. kgateway v2.0 설치 (L1)

helm repo add kgateway https://kgateway.dev/helm
helm install kgateway kgateway/kgateway \
  --namespace kgateway-system --create-namespace \
  --version 2.0.0 \
  --set gatewayClass.name=kgateway \
  --set controller.metrics.enabled=true

Step 3. Gateway 리소스 생성

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: llm-gateway
  namespace: kgateway-system
spec:
  gatewayClassName: kgateway
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - name: llm-tls-cert

Step 4. Bifrost v1.x (L2) 배포

helm install bifrost maximhq/bifrost \
  --namespace inference \
  --version 1.0.0 \
  --set providers.openai.apiKeyFrom=secret/openai \
  --set providers.anthropic.apiKeyFrom=secret/anthropic \
  --set providers.bedrock.region=ap-northeast-2 \
  --set cascade.enabled=true \
  --set semanticCache.enabled=true

Step 5. Cascade 또는 Semantic Router 정책 정의

• Cascade 예시: anthropic.claude-haiku-4-5 → anthropic.claude-sonnet-4-6 → anthropic.claude-opus-4-7 순 fallback
• Semantic Router 예시: 임베딩 BGE-M3 로 intent 분류 → code → Qwen3-Coder, reasoning → DeepSeek-V3
• references/inference-gateway-cascade-pattern.md 참조

Step 6. HTTPRoute 바인딩

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: llm-cascade
  namespace: inference
spec:
  parentRefs:
    - name: llm-gateway
      namespace: kgateway-system
  hostnames: ["llm.example.com"]
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1/chat/completions
      backendRefs:
        - name: bifrost
          port: 8080
      timeouts:
        request: 60s

Step 7. OTel Trace 검증

• Bifrost → OTel Collector → Langfuse 경로 확인
• langfuse.com 대시보드에서 trace 수신 여부 확인
• 누락 시 OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME 환경 변수 재점검

Good Examples

• 2-Tier: kgateway(L1) + Bifrost(L2) + vLLM(backend) — 관심사 명확 분리
• Cascade: Haiku 우선, 실패 코드 5xx 또는 정책 confidence 기반 fallback
• Semantic Router: intent embedding → 도메인 모델 선택, p95 latency 20% 개선 사례

Bad Examples (금지)

• 단일 Gateway 에 L1+L2 역할 혼재 → 각 레이어 최적화 불가
• API Key 를 HTTPRoute annotation 에 평문 저장 → Secrets 참조 필수
• Retry 없는 Cascade → 하나의 provider 장애로 전체 중단
• OTel Collector 미설정 → 트레이스 블랙홀

References

• Inference Gateway 라우팅 전략 (community resource)
• Cascade Routing 튜닝 (community resource)
• Inference Gateway 배포 가이드 (community resource)
• kgateway 공식 문서
• Kubernetes Gateway API
• Bifrost
• LiteLLM
• 플러그인 내부: ../../references/inference-gateway-cascade-pattern.md