글로벌 컨트롤 플레인

글로벌 컨트롤 플레인 (Global Control Plane)

각각 자체 데이터베이스, Redis, master key를 가진 여러 독립적인 LiteLLM 프록시 인스턴스를 관리하는 단일 LiteLLM UI를 배포해요.

Enterprise 기능

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

출처: 문서

본문

언제 사용하나요 (When to use this)

공유 데이터베이스 Multi-Region Deployment 토폴로지보다 블래스트 반경 격리가 전역 일관성보다 중요할 때 이것을 고르세요. 한 워커의 데이터베이스 장애가 다른 워커에 영향을 줄 수 없지만, 한 워커에서 만든 키는 다른 워커에서 인증되지 않아요. 키, 팀, 예산이 그것을 소유한 워커에 로컬이기 때문이에요. Multi-Region이 전체 절충안과 라이선싱 표를 다루며, 이 페이지가 행으로 나타나요.

이것을 그 페이지에 설명된 전용 admin 인스턴스와 혼동하지 마세요. 그 인스턴스도 admin 전용이고 LLM 트래픽을 서빙하지 않지만, 관리하는 리전 프록시와 하나의 데이터베이스를 공유하므로 단일 배포를 관리해요. 글로벌 컨트롤 플레인은 워커와 아무것도 공유하지 않고 많은 분리된 배포를 관리해요.

아키텍처 (Architecture)

👤 Admin
Global Control Plane - ADMIN UI ONLY - cp.example.com
  - 라우터가 아님. LLM 요청을 프록시하지 않음.
  - 관리자가 워커 간 전환하며 관리할 수 있게 해줌.
  - UI 관리 전용

Worker A - US East - worker-a.example.com
  - LLM 요청 처리
  - 🗄 자체 데이터베이스
  - ⚡ 자체 Redis

Worker B - EU West - worker-b.example.com
  - LLM 요청 처리
  - 🗄 자체 데이터베이스
  - ⚡ 자체 Redis

컨트롤 플레인은 admin UI를 서빙하고 모든 워커를 아는 LiteLLM 인스턴스예요. 관리자가 워커 간 전환하고 단일 UI에서 관리할 수 있게 하기 위해 순수하게 존재해요.

각 워커는 자신의 리전이나 팀의 LLM 요청을 처리하는 완전히 독립적인 LiteLLM 프록시예요. 워커는 자체 데이터베이스, Redis, 사용자, 키, 팀, 예산을 가져요.

설정 (Setup)

1. 컨트롤 플레인 구성 (Control Plane Configuration)

컨트롤 플레인은 모든 워커 인스턴스를 나열하는 worker_registry가 필요해요. 각 항목은 worker_id, name, url을 요구해요.

cp_config.yaml:

model_list: []
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL
worker_registry:
  - worker_id: "worker-a"
    name: "Worker A"
    url: "http://localhost:4001" # must start with http:// or https://
  - worker_id: "worker-b"
    name: "Worker B"
    url: "http://localhost:4002"

컨트롤 플레인 시작:

litellm --config cp_config.yaml --port 4000

2. 워커 구성 (Worker Configuration)

각 워커는 general_settings에 control_plane_url이 필요해요. 이는 워커에 /v3/login과 /v3/login/exchange 엔드포인트를 활성화해 컨트롤 플레인 UI가 교차 출처에서 인증할 수 있게 해줘요. 각 워커에 PROXY_BASE_URL도 설정해야 SSO 콜백 리다이렉트가 올바르게 해석돼요.

worker_a_config.yaml:

model_list: []
general_settings:
  master_key: «redacted:sk-…» # unique per worker
  database_url: os.environ/WORKER_A_DATABASE_URL # unique per worker
  control_plane_url: "http://localhost:4000"

PROXY_BASE_URL=http://localhost:4001 litellm --config worker_a_config.yaml --port 4001

레지스트리의 모든 워커에 대해 master key, 데이터베이스 URL, 포트를 바꿔가며 반복하세요. 워커는 다른 모든 면에서 일반적인 LiteLLM 프록시이므로, 프로덕션 배포 가이드가 변경 없이 적용돼요.

important

각 워커는 자체 master_key와 database_url을 가져야 해요. 이 아키텍처의 핵심은 워커가 독립적이라는 것입니다.

info

워커가 로드 밸런서 뒤에서 인스턴스를 둘 이상 실행한다면 그 워커에 Redis를 구성하세요 (콘피그의 cache 섹션). /v3/login이 발급하는 로그인 코드는 서버 측에 저장되므로, 공유 Redis 없이는 교환이 다른 인스턴스에 떨어져 401로 실패할 수 있어요.

3. SSO 구성 (선택) (SSO Configuration)

SSO는 표준 LiteLLM 프록시와 같은 방식으로 컨트롤 플레인 인스턴스에 구성돼요. 전체 지침은 SSO setup guide 참고. SSO를 사용하면 SSO 제공자 대시보드에서 각 워커 URL과 컨트롤 플레인 URL을 허용된 콜백 URL로 등록하세요.

컨트롤 플레인과 워커 하나가 실행되면 http://localhost:4000/ui를 여세요. 로그인 페이지에 워커 선택기가 보여야 해요.

동작 방식 (How It Works)

로그인 플로우 (Login Flow)

로드 시 UI는 컨트롤 플레인의 /.well-known/litellm-ui-config 엔드포인트를 읽으며, worker_registry가 설정되면 (ID, 이름, URL과 함께) is_control_plane: true를 보고해요. 컨트롤 플레인이므로 로그인 페이지는 워커 선택기 드롭다운을 보여줘요.

사용자는 워커를 선택하고 사용자 이름/비밀번호 또는 SSO로 로그인해요. UI는 선택한 워커의 /v3/login 엔드포인트를 호출해 인증하며, 이는 단일 사용 코드를 반환하고, 그다음 워커의 /v3/login/exchange에서 그 코드를 JWT로 교환해요. 그 후 모든 후속 API 호출을 그 워커로 향하게 하므로 컨트롤 플레인 UI에서 선택한 워커의 키, 팀, 모델, 예산을 관리해요.

로그인 후 사용자는 UI를 떠나지 않고 내비게이션 바 드롭다운에서 워커를 전환할 수 있어요. 전환은 로그인 페이지로 리다이렉트해 새 워커에 인증해요.