멀티 리전 배포

멀티 리전 배포 (Multi-Region Deployment)

같은 클라우드 공급자의 여러 리전에 LiteLLM 프록시 인스턴스를 두고, 모두 하나의 공유 PostgreSQL 데이터베이스에 연결해 운영할 수 있어요. 클라이언트는 대기 시간이 낮은 가장 가까운 리전으로 라우팅되고, 키·팀·사용자·지출 추적은 하나의 진실 공급원(single source of truth)이 있기 때문에 어디서나 일관돼요.

이 페이지는 지원되는 토폴로지, 리전 간 라이선스 동작 방식, 단계별 설정을 다뤄요. 각 리전에 프록시 자체를 배포하는 방법은 Production Deployment를 보세요.

출처: 문서

본문

같은 클라우드 공급자의 여러 리전에 LiteLLM 프록시 인스턴스를 실행하고, 모두 하나의 공유 PostgreSQL 데이터베이스에 연결해요. 클라이언트는 대기 시간이 낮도록 가장 가까운 리전으로 라우팅되고, 키·팀·사용자·지출 추적은 하나의 진실 공급원이 있어 어디서나 일관되게 유지돼요.

이 페이지는 지원되는 토폴로지, 리전 간 라이선스 동작, 단계별 설정을 다뤄요. 각 리전에 프록시 자체를 배포하는 방법은 Production Deployment를 보세요.

아키텍처 (Architecture)

AWSGoogle CloudAzure

가장 가까운 리전으로 라우팅되는 클라이언트

latency 또는 geo DNS 라우팅

Route 53 latency 기반 라우팅

us-east-1 (primary, 기본)

LiteLLM 인스턴스 - 리전 로드 밸런서 + 팟

리전별 Redis - 레이트 리밋, 라우터 상태, 캐시

PostgreSQL (primary) - 단일 공유 데이터베이스

eu-west-1 (secondary, 보조)

LiteLLM 인스턴스 - 리전 로드 밸런서 + 팟

리전별 Redis - 레이트 리밋, 라우터 상태, 캐시

읽기(선택적 복제본), 쓰기는 primary로 이동

읽기 복제본(선택) - DATABASE_URL_READ_REPLICA

하나의 Enterprise 라이선스가 모든 리전을 커버해요. 각 인스턴스는 같은 LITELLM_LICENSE를 검증하고, 사용자/팀 한도는 단일 공유 데이터베이스에서 집계돼요. 모든 인스턴스는 같은 LITELLM_MASTER_KEY와 LITELLM_SALT_KEY를 공유해야 해요.

토폴로지에는 세 가지 규칙이 있어요:

하나의 데이터베이스. 모든 리전의 프록시 인스턴스는 DATABASE_URL을 primary 리전에 호스팅된 같은 PostgreSQL 데이터베이스를 가리켜요. 이게 한 리전에서 만든 키가 모든 리전에서 동작하고, 예산과 지출 추적이 전역적으로 일관된 이유예요.
리전당 하나의 Redis. Redis는 한 리전의 인스턴스들 사이에서 레이트 리밋, 라우터 상태, 응답 캐싱을 처리해요. 리전 안에 두고, 단일 Redis를 크로스-리전 링크 뒤에 두면 모든 레이트 리밋 검사에 네트워크 왕복이 추가돼요.
하나의 클라우드 공급자. 모든 리전을 같은 클라우드 공급자에서 실행하세요.

같은 토폴로지가 active-active(DNS가 모든 클라이언트를 가장 가까운 리전으로 라우팅, 목표는 지연 시간) 또는 active-passive(모든 트래픽이 한 리전에, 두 번째 리전은 DNS 페일오버 레코드 뒤에 배포만 하고 유휴, 목표는 재해 복구)로 동작해요. 설정은 동일하고 DNS 정책만 달라요.

리전 간 라이선스 (Licensing across regions)

모든 리전이 하나의 데이터베이스를 공유하는 한, 단일 LiteLLM Enterprise 라이선스가 모든 리전을 커버해요.

각 프록시 인스턴스는 부여받은 LITELLM_LICENSE 키를 독립적으로 검증하고(서명된 페이로드에 대해 오프라인으로, 또는 라이선스 서버에 대해), 라이선스 검사는 인스턴스나 리전 수를 세지 않아요. 라이선스가 지니는 정량적 한도(최대 사용자, 최대 팀)는 데이터베이스에서 계산돼요. 모든 리전이 하나의 데이터베이스를 공유하면 그 수치가 한 번만 존재하므로, 라이선스는 한 번, 전역적으로 적용돼요.

따라서: 리전별로 별도 데이터베이스를 두는 것은 별도 디플로이먼트이며, 각각 자체 라이선스가 필요해요. 데이터베이스 두 개는 사용자·팀 수 두 세트, 키 두 세트, 라이선스 두 개를 의미해요.

토폴로지	데이터베이스	필요한 라이선스
멀티 리전, 공유 데이터베이스 (이 페이지)	1	1
리전별 독립 디플로이먼트	리전당 1	리전당 1
Global Control Plane	워커당 1	워커당 1

리전별로 완전히 독립된 디플로이먼트(자체 데이터베이스, Redis, 마스터 키, 라이선스)를 단일 UI로 관리하고 싶다면 이 페이지 대신 Global Control Plane(Enterprise)을 사용하세요. 이 방식은 글로벌 일관성을 폭발 반경 격리(blast-radius isolation)와 맞바꿔요: 한 리전의 데이터베이스 장애가 다른 리전에 영향을 줄 수 없지만, 키와 예산은 리전을 넘나들지 않아요.

요구사항 (Requirements)

모든 리전의 모든 프록시 인스턴스는 다음을 공유해야 해요. 이 중 어느 하나라도 리전 간에 다르면 디플로이먼트는 디버깅하기 어려운 방식으로 오작동해요(저장된 자격 증명을 복호화하지 못하는 인스턴스, 한 리전에서 인증 실패하는 키, 일관되지 않게 적용되는 시트 한도 등).

설정	반드시	이유
`DATABASE_URL`	모든 리전에서 같은 데이터베이스	키·팀·사용자·지출·라이선스 시트 수의 단일 진실 공급원
`LITELLM_MASTER_KEY`	모든 리전에서 동일	키는 공유 데이터베이스에 대해 검증됨, 마스터 키는 어디서나 일치해야 함
`LITELLM_SALT_KEY`	모든 리전에서 동일, 설정 후 절대 변경 금지	데이터베이스에 저장된 LLM 자격 증명을 암호화·복호화함. 다른 salt 키를 가진 인스턴스는 저장된 모델 자격 증명을 읽지 못함
`LITELLM_LICENSE`	모든 리전에서 같은 라이선스 키	각 인스턴스가 라이선스를 독립 검증, 하나의 키로 모두 활성화
`DISABLE_SCHEMA_UPDATE`	모든 프록시 인스턴스에서 `true`	스키마 마이그레이션은 모든 리전의 인스턴스들이 경쟁해서가 아니라 정확히 한 번(잡으로) 실행돼야 함

리전마다 추가로 Redis 인스턴스를 실행하고 그 리전의 프록시 설정(router_settings와 캐시 설정)에 넣어요. Redis 상태는 리전 단위예요: 레이트 리밋과 캐시된 응답은 요청을 서빙한 리전으로 범위가 한정돼요.

info

레이트 리밋(키·팀·사용자의 TPM/RPM)은 Redis로 적용돼요. 리전당 Redis 하나면 100 RPM 제한은 전역이 아니라 리전당 100 RPM이에요. 엄격히 전역 레이트 리밋이 필요하면 모든 인스턴스가 하나의 Redis를 공유해야 하는데, 이러면 원격 리전의 요청 경로에 크로스-리전 왕복이 추가돼요. 대부분의 디플로이먼트는 리전 단위 적용을 받아들여요.

설정 (Setup)

아래 단계는 이미 단일 리전 프로덕션 프록시(로드 밸런서, 프록시 인스턴스, Postgres, Redis)를 배포할 수 있다고 가정해요. 그렇지 않다면 Production Deployment 가이드와 프로덕션 체크리스트부터 시작하세요.

1. 공유 데이터베이스 준비하기

primary 리전에 PostgreSQL 데이터베이스 하나를 만들고 Helm 차트 또는 Terraform 모듈의 마이그레이션 잡을 사용해 스키마 마이그레이션을 그 데이터베이스에 정확히 한 번 실행해요. 모든 리전이 이 데이터베이스의 연결 문자열을 사용해요.

2. 리전 네트워크 연결하기

보조 리전의 프록시 인스턴스는 프라이빗 라우팅된 연결로 primary 리전의 데이터베이스에 도달해야 해요: AWS에서는 VPC peering 또는 Transit Gateway, GCP에서는 VPC Network Peering(지역 서브넷을 가진 글로벌 VPC도 동작), Azure에서는 VNet peering을 사용하세요. 각 보조 리전의 프록시 서브넷에서 데이터베이스의 보안 그룹/방화벽의 데이터베이스 포트(5432)를 열고, 연결에 TLS를 요구하세요(sslmode=require). 이 트래픽은 리전 경계를 넘어요. 보조 리전에서 캐시되지 않은 데이터베이스 읽기는 매번 인터-리전 왕복을 지불하는데, 그래서 4단계에서 리전별 읽기 복제본을 추가해요.

3. 각 리전에 프록시 인스턴스 배포하기

단일 리전과 똑같이 각 리전에 프록시를 배포하되 두 가지 차이가 있어요: DATABASE_URL을 리전 데이터베이스 대신 primary 리전 데이터베이스를 가리키도록 하고, 스키마 마이그레이션 잡만 primary 리전에서 실행하세요(보조 리전 Helm 값에서 migrationJob.enabled: false). 그래야 한 리전의 배포가 다른 리전의 마이그레이션과 공유 스키마에 대해 경쟁하지 않아요. 모든 리전을 같은 진실 공급원(하나의 Helm 값 파일 또는 Terraform 설정, 리전만 파라미터화)에서 배포해 리전 간 버전이나 설정이 어긋나지 않게 하세요.

primary 리전 (us-east-1)
보조 리전 (eu-west-1)

    DATABASE_URL="postgresql://litellm:***@db.us-east-1.internal:5432/litellm?sslmode=require"
    LITELLM_MASTER_KEY="sk-<same-everywhere>"
    LITELLM_SALT_KEY="sk-<same-everywhere-never-rotate>"
    LITELLM_LICENSE="<same-everywhere>"
    DISABLE_SCHEMA_UPDATE="true"
    REDIS_HOST="redis.us-east-1.internal"
    REDIS_PORT="6379"
    REDIS_PASSWORD="<regional>"

    # Same database as the primary region
    DATABASE_URL="postgresql://litellm:***@db.us-east-1.internal:5432/litellm?sslmode=require"
    LITELLM_MASTER_KEY="sk-<same-everywhere>"
    LITELLM_SALT_KEY="sk-<same-everywhere-never-rotate>"
    LITELLM_LICENSE="<same-everywhere>"
    DISABLE_SCHEMA_UPDATE="true"
    # Redis stays regional
    REDIS_HOST="redis.eu-west-1.internal"
    REDIS_PORT="6379"
    REDIS_PASSWORD="<regional>"

    # Optional: regional read replica (see next section)
    DATABASE_URL_READ_REPLICA="postgresql://litellm:***@db-replica.eu-west-1.internal:5432/litellm"

4. (선택) 리전별 읽기 복제본 추가하기

모든 요청은 데이터베이스에 대해 키를 인증해요(인메모리 캐싱이 있어 정상 트래픽은 매 호출마다 데이터베이스를 침 안 됨). 보조 리전은 리전 안에 PostgreSQL 읽기 복제본을 두고 DATABASE_URL_READ_REPLICA를 설정해 데이터베이스 읽기 지연을 줄일 수 있어요. LiteLLM은 읽기 전용 쿼리를 복제본으로, 모든 쓰기를 primary로 라우팅해요. 무엇이 어디로 라우팅되는지와 복제 지연 처리 방법은 Database Read Replica를 보세요.

쓰기(키 생성, 설정 변경, 지출 업데이트)는 항상 primary 리전의 데이터베이스로 가요. 지출 업데이트는 배치되므로 크로스-리전 쓰기 지연이 요청 경로에 있지 않아요.

5. 클라이언트를 가장 가까운 리전으로 라우팅하기

리전별 로드 밸런서 앞에 latency 기반 또는 geo DNS를 두세요: AWS의 Route 53 latency-based routing, GCP의 Cloud DNS geolocation routing policies, Azure의 Traffic Manager 또는 Front Door. 클라이언트는 하나의 호스트명을 사용해 가장 가까운 리전에 도착해요.

/health/readiness가 아니라 /health/liveliness로 각 리전의 헬스 체크를 하세요. Readiness는 데이터베이스에 도달할 수 없을 때마다 503을 반환하는데, 데이터베이스는 공유되므로 장애가 모든 리전의 readiness 체크를 한꺼번에 실패시켜 모든 리전을 DNS 로테이션에서 빼버려요. 정확히 allow_requests_on_db_unavailable이 캐시된 트래픽을 계속 서빙하게 했을 상황이에요. Liveliness는 리전의 프록시가 살아 있는지를 보고하며, 이게 DNS 페일오버 결정에 필요한 값이에요.

6. 검증하기

primary 리전의 Admin UI(https://llm.example.com/ui)를 열고 Virtual Keys로 가서 키를 만들어요.
보조 리전의 UI를 직접 열어(https://eu.llm.example.com/ui) Test Key 플레이그라운드로 가서 방금 만든 키를 붙여넣고 요청을 보내요. 두 리전이 같은 데이터베이스로 키를 검증하므로 성공해요.
Virtual Keys로 돌아가 키에 보조 리전을 통해 보낸 요청의 지출이 표시되는지 확인해요. UI 흐름 자체는 Quickstart에 스크린샷으로 나와 있어요.

(선택) 전용 admin 인스턴스

기본적으로 모든 인스턴스가 LLM 트래픽과 admin 트래픽(UI와 관리 API)을 모두 서빙해요. 멀티 리전 디플로이먼트에서 한 인스턴스를 admin 전용으로 지정하고 리전별 인스턴스에서 admin 표면을 제거할 수 있어요. 그러면 관리 접근을 하나의 호스트명 뒤에 두고 LLM 트래픽을 서빙하는 인스턴스들의 공격 표면을 줄여요.

Enterprise 기능이에요.

이 기능은 LiteLLM Enterprise 라이선스가 필요해요. 무료 30일 체험을 시작하거나 데모를 예약하세요. Enterprise가 포함하는 것을 확인하세요.

DISABLE_ADMIN_ENDPOINTS와 DISABLE_LLM_API_ENDPOINTS는 Enterprise 기능이에요.

Admin 인스턴스
리전별 인스턴스

    # Serves the UI and management APIs, refuses LLM traffic
    DISABLE_LLM_API_ENDPOINTS="true"
    DATABASE_URL="postgresql://[email protected]:5432/litellm"
    LITELLM_MASTER_KEY="sk-<same-everywhere>"

    # Serve LLM traffic, refuse admin traffic
    DISABLE_ADMIN_UI="true"
    DISABLE_ADMIN_ENDPOINTS="true"
    DATABASE_URL="postgresql://[email protected]:5432/litellm"
    LITELLM_MASTER_KEY="sk-<same-everywhere>"

변수	기본값	`true`일 때 효과
`DISABLE_ADMIN_UI`	`false`	`/ui`의 웹 UI를 사용할 수 없게 됨
`DISABLE_ADMIN_ENDPOINTS`	`false`	관리 엔드포인트(`/key/`, `/user/`, `/team/`, `/model/`)가 오류 반환. LLM 엔드포인트, `/health`, `/metrics`는 계속 동작
`DISABLE_LLM_API_ENDPOINTS`	`false`	LLM 엔드포인트(`/chat/completions`, `/v1/*`, provider pass-through 라우트)가 오류 반환. 관리 엔드포인트는 계속 동작하고, UI가 모델을 나열할 수 있도록 `/models`는 유지

FAQ

멀티 리전이 아예 필요할까요? 보통은 아니에요. 멀티-AZ 데이터베이스와 Redis를 가진 단일 리전 디플로이먼트도 이미 존(zone) 장애를 버텨요. Production Best Practices를 보세요. 먼 사용자에게 더 낮은 지연이 필요하거나 크로스-리전 재해 복구가 필요할 때 리전을 추가하세요.

멀티 리전에 Enterprise 라이선스가 필요한가요? 공유 데이터베이스 토폴로지 자체는 오픈소스 프록시에서 동작해요. Enterprise 기능은 리전 간에 하나의 라이선스로 커버되며, "리전 간 라이선스"에서 설명했어요.

primary 리전의 데이터베이스가 다운되면 어떻게 되나요? 모든 리전이 데이터베이스 접근을 잃어요: 키 검증은 캐시로 폴백하고, 데이터베이스가 돌아올 때까지 관리 작업은 실패해요. 데이터베이스가 이 아키텍처의 단일 커플링 지점이에요. general_settings.allow_requests_on_db_unavailable: true를 설정해 프록시가 장애 중에도 이미 캐시된 키의 트래픽을 계속 서빙하게 하고(graceful DB unavailability), 데이터베이스를 자동 페일오버와 함께 멀티-AZ로 운영하고, 그래도 격리가 부족하다면 Global Control Plane을 대신 고려하세요.

리전마다 다른 LiteLLM 버전을 실행할 수 있나요? 롤링 업그레이드 중에는 잠깐 가능해요. 정상 상태에서 혼합 버전을 실행하지 마세요; 공유 데이터베이스 스키마는 최신 버전을 따르고, 마이그레이션은 업그레이드당 정확히 한 번 실행돼야 해요.

멀티 리전 배포