Kubernetes에서 LLM Gateway를 직접 구축하기: 주말 가이드

Self-Host an LLM Gateway on Kubernetes: A Weekend Guide

요약 (TL;DR)

Kubernetes에서 LLM gateway를 직접 구축하면 외부 모델 라우팅, 자격 증명 보안, 토큰 예산 책정, 캐싱 등을 클러스터 경계 내에서 완전히 처리할 수 있습니다.
Maxim AI가 Go로 작성한 오픈 소스 AI 게이트웨이인 Bifrost는 초당 5,000 요청에서 라우팅 오버헤드를 단 11 마이크로초만 추가합니다.
Helm을 사용하여 gateway를 배포하면 내장된 고가용성(high availability), 수평 자동 스케일링(horizontal autoscaling), Kubernetes pod 검색 기능, 그리고 네이티브 Prometheus 원격 측정(telemetry) 기능을 제공합니다.
팀은 PostgreSQL 스토리지를 프로비저닝하고, 암호화된 API 키를 주입하며, Ingress 컨트롤러를 구성하는 것만으로 단 하루의 주말 동안 운영 가능한 수준의 Kubernetes 배포를 완료할 수 있습니다.

여러 상용 및 로컬 모델 제공업체에 걸쳐 실행되는 프로덕션 AI 애플리케이션은 업스트림 API가 속도 제한 오류(rate-limit errors), 네트워크 시간 초과(network timeouts) 또는 갑작스러운 중단이 발생하면 실패합니다. 플랫폼 엔지니어들은 개별 마이크로서비스에 제공업체 자격 증명 및 재시도 루프를 하드코딩하는 대신, 전용 진입점(ingress point)을 통해 추론 호출을 라우팅합니다. Kubernetes에서 LLM gateway를 직접 구축한다는 것은 프롬프트 로그를 제3자 서비스로 전송하지 않으면서 모델 라우팅, 자격 증명 및 원격 측정을 제어하기 위해 자체 클라우드 경계 내에 중앙 집중식 프록시를 운영하는 것을 의미합니다. Bifrost는 고성능 동시성 환경을 위해 설계된 오픈 소스 AI 게이트웨이로, 지원되는 제공업체(supported providers) 전반에 걸쳐 드롭인 SDK 대체품을 지원합니다. 이 주말 가이드에서는 Kubernetes에서 확장 가능한 LLM gateway를 실행하는 데 필요한 아키텍처 선택, Helm 구성, Ingress 설정 및 관측 가능성(observability) 파이프라인을 안내합니다.

Kubernetes에서 LLM 게이트웨이를 직접 구축하는 이유?

자체 호스팅(self-hosted) LLM 게이트웨이는 조직의 기존 Kubernetes 인프라 내에서 AI 라우팅, 키 로테이션, 요청 거버넌스를 중앙 집중화하여 보안 사각지대와 벤더 종속성(vendor lock-in)을 제거합니다. 게이트웨이는 모든 개발자 파드에 원시 제공업체 키(raw provider keys)를 노출하는 대신, 가상 자격 증명(virtual credentials)을 통해 요청을 수락하고, 정책 경계를 확인하며, 공급업체 간 트래픽을 분배합니다.

+-----------------------------------------------------------------------
|                         Kubernetes 클러스터                            |
|                                                                       |
...

엔지니어링 팀이 생성형 AI 기능을 확장할 때, 거의 즉시 다섯 가지 인프라 문제가 발생합니다:

자격 증명 분산(Credential dispersion): 수십 개의 Kubernetes 네임스페이스, 시크릿, 개발자 저장소에 독점 API 키를 분산시키는 것은 비밀 유출 위험을 증가시킵니다.
공급업체 불안정성(Provider instability): 상위 공급업체의 다운타임이나 속도 제한(HTTP 429 상태 코드)은 복잡한 폴백 로직이 모든 서비스에 재구현되지 않는 한 애플리케이션 워크플로우를 중단시킵니다.
비용 불투명성(Cost opacity): 중앙 집중식 기여도 추적 없이는 플랫폼 팀이 어떤 마이크로서비스나 사용자 그룹이 토큰 급증을 발생시키는지 추적할 수 없습니다.
규정 준수 경계(Compliance boundaries): HIPAA, SOC 2 또는 GDPR의 적용을 받는 규제 환경은 프롬프트 거주지(prompt residency)에 대한 엄격한 통제를 요구하며, 데이터가 중간 SaaS 프록시를 통해 흐르는 것을 방지합니다.
지연 시간 페널티(Latency penalties): 프록시 계층 추가는 프록시 아키텍처가 밀리초 단위의 병목 현상을 유발할 경우 스트리밍 텍스트 토큰의 사용자 경험을 저하시킬 수 있습니다.

게이트웨이를 Kubernetes 내부에서 운영하면 이러한 운영상의 문제들이 해결됩니다. 클러스터 스케줄러가 파드(pod)의 상태를 관리하고, 네이티브 서비스들은 사설 서브넷을 통해 내부 RPC를 라우팅하며, in-VPC 배포는 암호화되지 않은 프롬프트가 승인된 모델 제공업체로 라우팅되기 전에 외부 인프라에 절대 닿지 않도록 보장합니다.

Kubernetes에서 자체 호스팅 LLM 게이트웨이 아키텍처

Kubernetes 기반의 프로덕션 LLM 게이트웨이 아키텍처는 상태 비저장(stateless) 라우팅 데이터 플레인과 PostgreSQL 및 Redis와 같은 상태 저장(stateful) 스토리지 레이어를 분리합니다. 게이트웨이 파드들은 HTTP 및 gRPC 트래픽을 처리하고, 클라이언트 파드로 Server-Sent Events (SSE)를 스트리밍하며, 노드 전반에 걸쳐 클러스터 상태를 동기화합니다.

A sleek modern networking switch in an infrastructure rack with fiber-optic strands splitting cleanly into multiple illu

배포를 설계할 때, 플랫폼 엔지니어들은 개발용 경량의 단일 복제본(single-replica) 설정과 미션 크리티컬 워크로드를 위한 다중 복제본 클러스터 토폴로지 중 하나를 선택해야 합니다. Bifrost는 공식 Helm 차트를 통해 두 가지 운영 모델을 기본적으로 지원합니다.

배포 모델	컴퓨팅 패턴	스토리지 백엔드	상태 동기화	대상 워크로드
샌드박스 / 스테이징	StatefulSet (1 복제본)	로컬 SQLite (PersistentVolumeClaim)	단일 프로세스 메모리	로컬 개발자 클러스터, 통합 테스트
...

프로덕션 환경 설정에서는 상태 저장 구성 요소들이 게이트웨이 파드들과 분리되어 있어야 합니다. PersistentVolumeClaim의 SQLite는 샌드박스에 잘 작동하지만, 여러 복제본으로 확장할 때 공유 영구 스토리지는 잠금(locking) 문제를 야기합니다. 관리형 PostgreSQL 인스턴스를 백엔드로 사용하는 상태 비저장 Deployment는 Horizontal Pod Autoscaler (HPA)가 CPU 및 동시 요청 지표를 기반으로 파드를 동적으로 확장할 수 있게 합니다.

전제 조건 및 사전 클러스터 계획

엔터프라이즈급 LLM 게이트웨이를 배포하려면 버전 1.19 이상이 실행되는 Kubernetes 클러스터, kubectl을 통한 관리자 접근 권한, 그리고 Helm 3.2.0 이상이 필요합니다. 또한, 로컬 캐싱에 영구 볼륨(persistent volumes)이 필요한 경우 클러스터에 기본 StorageClass가 구성되어 있는지 확인하세요.

매니페스트를 적용하기 전에 다음 사전 점검(pre-flight preparations)을 완료해야 합니다:

네임스페이스 격리 (Namespace Isolation): 네트워크 정책, 역할 바인딩(role bindings), 비밀 정보(secrets)를 격리하기 위해 별도의 네임스페이스(예: bifrost)를 할당합니다.
PostgreSQL 데이터베이스: UTF-8 인코딩을 사용하는 전용 PostgreSQL 데이터베이스 인스턴스(버전 14 이상)를 프로비저닝합니다. Kubernetes 워커 노드 서브넷에서 데이터베이스 포트로의 네트워크 연결이 보장되는지 확인하세요.
마스터 암호화 키 (Master Encryption Key): 제공업체 토큰 및 휴식 상태(at rest) 가상 키를 암호화하기 위해 OpenSSL을 사용하여 암호학적으로 안전한 32바이트 키를 생성합니다.
제공업체 자격 증명 (Provider Credentials): OpenAI, Anthropic, AWS Bedrock, Google Vertex AI 또는 vLLM과 같은 로컬 인클러스터 엔드포인트에 대한 API 키를 모읍니다.
Ingress 및 DNS: 외부 또는 크로스 클러스터 액세스가 필요한 경우 Ingress 컨트롤러(예: ingress-nginx)가 작동하는지 확인합니다.

공식 Kubernetes 네트워킹 문서에 따르면, 명시적인 네임스페이스와 표준 Ingress 컨트롤러를 사용하면 마이크로서비스 경계를 넘나드는 네트워크 정책 관리 및 TLS 종료(TLS termination)가 간소화됩니다.

1단계: 스토리지, 비밀 정보, 그리고 Helm 리포지토리 구성

Bifrost Helm 리포지토리를 초기화하고 민감한 자격 증명을 보관할 Kubernetes 비밀 정보를 생성하여 토요일 아침에 설정을 시작합니다. API 키나 데이터베이스 비밀번호를 평문(plaintext) Helm 값 파일에 절대 저장하지 마세요.

먼저, 공식 Bifrost Helm 리포지토리를 추가하고 업데이트합니다:

helm repo add bifrost https://maximhq.github.io/bifrost/helm-charts
helm repo update

다음으로, 전용 네임스페이스를 생성합니다:

kubectl create namespace bifrost

마스터 암호화 키를 생성하여 네이티브 Kubernetes Secret 내부에 저장합니다. 이 키는 데이터베이스의 민감한 자격 증명을 보호합니다:

# 32바이트 base64 인코딩된 키 생성
ENCRYPTION_KEY=$(openssl rand -base64 32)

...

업스트림 제공자 자격 증명과 PostgreSQL 연결 매개변수를 포함하는 두 번째 Secret을 생성합니다:

kubectl create secret generic bifrost-core-secrets \
  --namespace bifrost \
  --from-literal=postgres-password="YourSecureDbPasswordHere" \
...

네이티브 Kubernetes 메커니즘을 통해 Secret을 관리하면, Kubernetes External Secrets Operator를 사용하여 HashiCorp Vault, AWS Secrets Manager 또는 Google Secret Manager와 같은 외부 Secret 저장소와의 통합이 가능합니다.

2단계: Helm과 고가용성(High Availability)으로 Bifrost 배포하기

Bifrost를 고가용성 모드로 배포하면 워커 노드가 실패하거나 롤링 업데이트를 거치더라도 들어오는 추론 요청 처리가 계속됨을 보장합니다. 이 단계에서는 구조화된 values.yaml 파일을 사용하여 다중 복제본 스케일링, 데이터베이스 연결성 및 리소스 예약 설정을 구성합니다.

로컬 배포 설정 파일인 bifrost-production-values.yaml을 생성합니다:

# bifrost-production-values.yaml
image:
  repository: maximhq/bifrost
...

커스텀 구성 파일을 사용하여 Helm 릴리스를 적용합니다:

helm install bifrost bifrost/bifrost \
  --namespace bifrost \
  -f bifrost-production-values.yaml

이 설정은 Pod anti-affinity 규칙을 지정하여 Kubernetes가 게이트웨이 복제본들을 서로 다른 물리적 워커 노드에 스케줄링하도록 지시합니다. 클러스터링은 네이티브 Kubernetes API discovery를 사용하여 피어 Pod를 찾고 클러스터 전반에 걸쳐 상태를 동기화합니다.

모든 Pod가 Running 상태에 도달했는지 확인합니다:

kubectl get pods -n bifrost -l app.kubernetes.io/name=bifrost

3단계: Ingress, TLS 및 Health Probes 구성하기

LLM 게이트웨이를 클러스터 내부 또는 외부의 클라이언트 마이크로서비스에 노출하려면 신뢰할 수 있는 네트워킹 규칙과 지속적인 상태 확인(health checks)이 필요합니다. LLM 토큰 스트리밍은 장기간 유지되는 HTTP 연결에 의존하므로, 인그레스 프록시(ingress proxies)는 생성 도중 연결 끊김을 방지하도록 구성되어야 합니다.

Bifrost는 8080 포트에서 HTTP 트래픽을 처리하며 동일한 포트에 전용 /health 엔드포인트를 노출합니다. Helm values 또는 배포 매니페스트(deployment manifests)에 준비성(readiness) 및 활성 상태 확인(liveness probes)을 구성하세요:

livenessProbe:
  httpGet:
    path: /health
...

ingress-nginx를 통한 인그레스 라우팅의 경우, 프록시 응답 버퍼링을 비활성화하는 Ingress 매니페스트를 정의해야 합니다. 버퍼링은 Server-Sent Events(SSE)를 방해하여 사용자 대상 애플리케이션의 최초 토큰까지 걸리는 시간(time-to-first-token, TTFT)을 증가시킵니다.

# bifrost-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
...

인그레스 매니페스트를 적용합니다:

kubectl apply -f bifrost-ingress.yaml

적용되면 애플리케이션은 해당 게이트웨이의 완전한 도메인 이름(fully qualified domain name, FQDN)을 사용하여 호출할 수 있습니다. Bifrost는 OpenAI 호환 SDK를 위한 드롭인 대체품(drop-in replacement) 역할을 하며, 애플리케이션 코드에서 기본 URL 매개변수만 변경하면 됩니다.

4단계: 모델 라우팅, 폴백 및 가상 키 설정

지능형 라우팅, 폴백 체인(fallback chains), 그리고 가상 키를 구성하는 것은 제공업체 서비스 중단 시에도 복원력 있는 운영을 보장하고 부서별 지출 통제를 강제합니다. 게이트웨이는 모델 변환을 투명하게 처리하여 클라이언트 파드(client pods)가 표준 모델 별칭을 요청할 수 있도록 하고, 게이트웨이가 사용 가능한 백엔드로 라우팅합니다.

Bifrost의 구성 엔진을 통해 관리자는 자동 폴백을 구성합니다. 기본 제공업체가 HTTP 500 또는 429 상태 코드를 반환하면, 트래픽은 예외를 클라이언트 파드에 발생시키지 않고 즉시 대체 모델이나 제공업체로 전환됩니다.

Incoming Request: "claude-3-5-sonnet"
                  |
                  v
...

팀 간 접근을 관리하려면 [가상 키(virtual keys)](https://docs.getbifrost.ai/features/governance/virtual-keys)를 구성하세요. 가상 키는 특정 애플리케이션 배포 또는 팀에 발급되는 가상의 토큰으로, 예산(budget), 속도 제한(rate limits), 허용 모델 목록을 강제합니다.

{
"name": "data-science-team-key",
"budget": {
...