pod 간 공유 헬스 체크 상태

pod 간 공유 헬스 체크 상태 (Shared Health Check State Across Pods)

이 기능은 여러 LiteLLM 프록시 pod 간에 헬스 체크를 조정해서 중복 헬스 체크를 피하고 비용을 줄여요.

개요

여러 LiteLLM 프록시 pod(예: Kubernetes)를 실행할 때, 각 pod는 보통 모든 모델에 대해 자체 독립 헬스 체크를 실행해요. 이로 인해 다음이 발생할 수 있어요:

pod 간 중복 헬스 체크
비싼 모델(예: Gemini 3.1 Pro)의 비용 증가
불필요한 모니터링/로깅 노이즈
비효율적인 리소스 사용

공유 헬스 체크 상태 기능은 다음으로 해결해요:

Redis를 사용해 헬스 체크 조정
구성 가능한 TTL로 결과 캐싱
한 번에 하나의 pod만 헬스 체크를 실행하도록 분산 락 사용
다른 pod가 중복 체크 대신 캐시된 결과를 읽을 수 있게 허용

동작 방식

1. 락 획득

pod가 헬스 체크를 실행해야 할 때:

Redis 락 획득을 시도
성공하면 헬스 체크 실행
실패하면 잠시 기다렸다가 캐시된 결과 확인

2. 결과 캐싱

헬스 체크 실행 후:

결과가 구성 가능한 TTL로 Redis에 캐시
다른 pod가 이 캐시된 결과를 읽을 수 있음
캐시에 추적용 타임스탬프와 pod ID 포함

3. 폴백 동작

Redis를 사용할 수 없거나 캐시가 만료된 경우:

pod는 헬스 체크를 로컬로 실행하는 것으로 폴백
시스템은 정상적으로 계속 동작

구성

공유 헬스 체크 활성화

proxy_config.yaml에 추가하세요:

    general_settings:  
      # Enable background health checks (required)  
      background_health_checks: true  
        
      # Enable shared health check state across pods  
      use_shared_health_check: true  
        
      # Health check interval (seconds)  
      health_check_interval: 300  # 5 minutes  
      
    # Redis configuration (required for shared health check)  
    litellm_settings:  
      cache: true  
      cache_params:  
        type: redis  
        host: your-redis-host  
        port: 6379  
        password: your-redis-password

환경 변수

이 기능 자체는 config 파일의 general_settings.use_shared_health_check로만 활성화돼요. 전용 환경 변수는 없어요. 캐시와 락 TTL은 환경 변수로 조정할 수 있어요:

    # Health check TTL (seconds)  
    export DEFAULT_SHARED_HEALTH_CHECK_TTL=300  
      
    # Lock TTL (seconds)  
    export DEFAULT_SHARED_HEALTH_CHECK_LOCK_TTL=60

요구 사항

Redis: 공유 상태 조정에 필수
백그라운드 헬스 체크: 활성화돼야 함(background_health_checks: true)
여러 pod: 프록시 인스턴스 2개 이상일 때 가장 유리

API 엔드포인트

공유 헬스 체크 상태 확인

    GET /health/shared-status

공유 헬스 체크 조정에 대한 정보를 반환해요:

    {  
      "shared_health_check_enabled": true,  
      "status": {  
        "pod_id": "pod_1703123456789",  
        "redis_available": true,  
        "lock_ttl": 60,  
        "cache_ttl": 300,  
        "lock_owner": "pod_1703123456788",  
        "lock_in_progress": true,  
        "cache_available": true,  
        "cache_age_seconds": 45.2,  
        "last_checked_by": "pod_1703123456788"  
      }  
    }

모니터링

헬스 체크 상태

공유 헬스 체크 상태를 모니터링해 제대로 조정되는지 확인하세요:

    curl -H "Authorization: Bearer ***" \  
      http://your-proxy-host/health/shared-status

로그

다음 로그 메시지들을 찾아보세요:

    INFO: Initialized shared health check manager  
    INFO: Pod pod_123 acquired health check lock  
    INFO: Pod pod_123 released health check lock  
    INFO: Cached health check results for 5 healthy and 0 unhealthy endpoints  
    DEBUG: Using cached health check results

문제 해결

흔한 문제

1. 공유 헬스 체크가 동작하지 않음

증상: 각 pod가 여전히 독립 헬스 체크를 실행

해결책:

Redis가 구성되고 접근 가능한지 확인
use_shared_health_check: true가 설정됐는지 확인
background_health_checks: true가 활성화됐는지 확인
로그에서 Redis 연결 확인

2. Redis 연결 문제

증상: 헬스 체크가 로컬 실행으로 폴백

해결책:

Redis host, port, 자격증명 확인
pod와 Redis 사이의 네트워크 연결 확인
Redis 서버 로그에서 오류 모니터링

3. 락이 해제되지 않음

증상: 한 pod가 락을 무기한 보유

해결책:

락에는 자동 TTL이 있음(기본 60초)
pod 로그에서 락 해제 메시지 확인
Redis TTL 설정 확인

디버그 모드

상세한 조정을 보려면 디버그 로깅을 활성화하세요:

    general_settings:  
      set_verbose: true

성능 영향

이점

API 호출 감소: 간격당 하나의 pod만 헬스 체크 실행
비용 절감: 특히 비싼 모델에서 두드러짐
더 나은 리소스 활용: pod 간 중복 작업 감소
깔끔한 모니터링: 로그와 메트릭의 노이즈 감소

오버헤드

Redis 연산: 락/캐시 연산에 대한 최소 오버헤드
네트워크 레이턴시: Redis 통신을 위한 작은 지연
메모리 사용량: 무시할 만한 추가 메모리 사용

모범 사례

1. Redis 구성

지속성이 활성화된 Redis 사용
적절한 메모리 한도 구성
Redis 모니터링 및 알림 설정

2. TTL 설정

health_check_interval을 원하는 체크 빈도로 설정
특별한 요구가 없다면 기본 TTL 값 사용
비싼 모델의 경우 모델별 타임아웃 고려

3. 모니터링

공유 헬스 체크 상태 엔드포인트 모니터링
Redis 연결 문제에 대한 알림 설정
헬스 체크 비용과 빈도 추적

4. 확장

기능은 어떤 수의 pod에서도 동작
pod가 많을수록 조정 이점이 큼
고가용성을 위해 Redis 클러스터 고려

예시 구성

완전한 예시

    # proxy_config.yaml  
    model_list:  
      - model_name: gpt-5.6-terra  
        litellm_params:  
          model: gpt-5.6-terra  
          api_key: os.environ/OPENAI_API_KEY  
        model_info:  
          health_check_timeout: 30  # 30 second timeout for health checks  
      
    general_settings:  
      # Enable background health checks  
      background_health_checks: true  
        
      # Enable shared health check coordination  
      use_shared_health_check: true  
        
      # Health check interval (5 minutes)  
      health_check_interval: 300  
        
      # Health check details  
      health_check_details: true  
      
    litellm_settings:  
      # Redis configuration  
      cache: true  
      cache_params:  
        type: redis  
        host: redis-cluster.example.com  
        port: 6379  
        password: os.environ/REDIS_PASSWORD  
        ssl: true

Kubernetes 예시

    # deployment.yaml  
    apiVersion: apps/v1  
    kind: Deployment  
    metadata:  
      name: litellm-proxy  
    spec:  
      replicas: 3  # Multiple pods for coordination  
      template:  
        spec:  
          containers:  
          - name: litellm-proxy  
            image: docker.litellm.ai/berriai/litellm:latest  
            args: ["--config", "/app/proxy_config.yaml"]  # config sets use_shared_health_check: true  
            env:  
            - name: REDIS_HOST  
              value: "redis-service"  
            - name: REDIS_PASSWORD  
              valueFrom:  
                secretKeyRef:  
                  name: redis-secret  
                  key: password

마이그레이션

독립 헬스 체크에서 전환

Redis 활성화: Redis가 구성되고 접근 가능한지 확인
백그라운드 헬스 체크 활성화: background_health_checks: true 설정
공유 헬스 체크 활성화: use_shared_health_check: true 설정
배포: 프록시 구성 업데이트
모니터링: /health/shared-status 엔드포인트 확인

롤백

공유 헬스 체크를 비활성화하려면:

    general_settings:  
      use_shared_health_check: false  
      # background_health_checks can remain true for independent checks

pod 간 공유 헬스 체크 상태