AWS ElastiCache IAM 인증

AWS ElastiCache IAM 인증 (AWS ElastiCache IAM Authentication)

LiteLLM의 Redis 캐시를 IAM 인증으로 AWS ElastiCache(Redis OSS 또는 Valkey)에 연결해요. 그러면 콘피그, 환경, 시크릿 스토어 어디에도 Redis 비밀번호가 존재하지 않아요.

출처: 문서

본문

왜 사용하나요 (Why use it)

ElastiCache와 Valkey는 Redis 프로토콜을 지원하므로 LiteLLM은 항상 그들과 통신할 수 있었어요. 빠졌던 것은 인증 이야기였어요. IAM 인증으로 클라이언트는 비밀번호 대신 수명이 짧은 AWS SigV4 토큰을 제시하고, ElastiCache는 매 연결마다 IAM 정책에 대해 이를 검증해요.

이는 정적 Redis 비밀번호가 줄 수 없는 네 가지를 사줘요. 액세스는 공유 시크릿이 아니라 IAM으로 부여되므로, 비밀번호를 교체하고 모든 복제본을 재배포하는 대신 정책을 분리해 해지해요. 모든 연결 시도가 IAM 주체에 귀속돼요. 토큰 자체는 15분 동안 유효하고 새 연결마다 재서명되므로, 유출된 토큰은 거의 무가치해요. 그리고 서명 자격 증명이 표준 AWS 체인에서 오므로, IRSA, EC2 인스턴스 프로파일, ECS 태스크 역할 아래 실행되는 프록시는 재시작 없이 교체된 자격 증명을 스스로 얻어요.

이것이 존재하기 전에는 IAM 인증을 켜는 것이 redis-py에 Python 자격 증명 제공자 객체를 넘겨야 했는데, YAML 콘피그로 표현할 수 없었어요. 운영자는 LiteLLM을 패치하거나 커스텀 통합을 작성해야 했어요. 이제는 네 가지 설정이에요.

요구사항 (Requirements)

캐시에서 전송 중 암호화가 활성화되어야 해요. LiteLLM은 일반 텍스트 연결에서 IAM 인증을 조용히 다운그레이드하지 않고 시작을 거부하므로, ssl: true가 필수예요. ElastiCache Serverless는 항상 전송 중 암호화를 해요. 자체 설계 클러스터는 --transit-encryption-enabled로 생성해야 해요.

또한 boto3 설치(litellm[proxy]에 포함)와 IAM 모드로 생성된 ElastiCache 사용자가 필요해요. ElastiCache는 그러한 사용자의 이름과 id가 동일해야 한다고 요구해요.

워크스루 (Walkthrough)

이는 EKS에서 IRSA로 ElastiCache Serverless Valkey 캐시에 인증하는 LiteLLM 프록시를 설정해요. 전반에 자체 계정 id, 리전, 이름으로 바꾸세요.

1. IAM 모드로 ElastiCache 사용자 생성

사용자 이름과 사용자 id가 일치해야 하고, 액세스 문자열이 프록시가 Redis 안에서 무엇을 할 수 있는지 제어해요. on ~* +@all은 전체 키스페이스를 주는데, 이는 응답 캐시가 기대하는 것입니다.

aws elasticache create-user \
  --user-id litellm-cache \
  --user-name litellm-cache \
  --engine valkey \
  --authentication-mode Type=iam \
  --access-string "on ~* +@all"

2. 사용자를 사용자 그룹에 넣고 캐시에 연결

모든 사용자 그룹은 default라는 구성원이 필요해요. 이 엔진용이 아직 없다면, 실제 액세스가 IAM 사용자를 통해 실행되도록 비활성화된 플레이스홀더를 생성하세요.

aws elasticache create-user-group \
  --user-group-id litellm-cache-users \
  --engine valkey \
  --user-ids default-placeholder litellm-cache

aws elasticache create-serverless-cache \
  --serverless-cache-name litellm-cache \
  --engine valkey \
  --user-group-id litellm-cache-users \
  --security-group-ids sg-0123456789abcdef0 \
  --subnet-ids subnet-0123456789abcdef0 subnet-0fedcba9876543210

이미 존재하는 캐시에 그룹을 연결하려면 대신 modify-serverless-cache --user-group-id 또는 modify-replication-group --user-group-ids를 사용하세요.

3. 프록시가 실행되는 역할에 elasticache:Connect 부여

정책은 캐시와 사용자 둘 다를 명명해야 해요. 하나만 부여하면 연결 시점에 fail closed 돼요.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "elasticache:Connect",
      "Resource": [
        "arn:aws:elasticache:us-east-1:123456789012:serverlesscache:litellm-cache",
        "arn:aws:elasticache:us-east-1:123456789012:user:litellm-cache"
      ]
    }
  ]
}

그 정책을 서비스 계정이 가정하는 IAM 역할에 연결하고, pod가 받도록 서비스 계정에 어노테이션하세요.

apiVersion: v1
kind: ServiceAccount
metadata:
  name: litellm
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/litellm-proxy

자체 설계 클러스터의 캐시 ARN은 대신 arn:aws:elasticache:<region>:<account>:replicationgroup:<replication-group-id>예요.

4. LiteLLM을 캐시로 지정

ElastiCache Serverless와 모든 cluster mode 활성 캐시는 클러스터 인식 클라이언트가 필요하므로 redis_startup_nodes를 사용하세요. aws_iam_cache_name은 엔드포인트 호스트명이 아니라 캐시 이름이에요. 그 이름이 서명되기 때문이에요.

Serverless

litellm_settings:
  cache: true
  cache_params:
    type: redis
    redis_startup_nodes:
      [{ "host": "litellm-cache-abc123.serverless.use1.cache.amazonaws.com", "port": 6379 }]
    ssl: true
    aws_iam_auth: true
    aws_iam_user_name: litellm-cache
    aws_iam_cache_name: litellm-cache
    aws_iam_region: us-east-1
    aws_iam_serverless: true

자체 설계 클러스터

클러스터 모드 비활성 복제 그룹의 경우 host를 프라이머리 엔드포인트로 지정하고 aws_iam_serverless는 설정하지 마세요. aws_iam_cache_name은 복제 그룹 id예요.

litellm_settings:
  cache: true
  cache_params:
    type: redis
    host: master.litellm-cache.abc123.use1.cache.amazonaws.com
    port: 6379
    ssl: true
    aws_iam_auth: true
    aws_iam_user_name: litellm-cache
    aws_iam_cache_name: litellm-cache
    aws_iam_region: us-east-1

환경 변수

모든 설정에는 REDIS_ 접두사 환경 변수 대응이 있으며, 값이 시크릿 매니저나 Helm values 파일에서 올 때 더 잘 맞아요.

REDIS_CLUSTER_NODES='[{"host": "litellm-cache-abc123.serverless.use1.cache.amazonaws.com", "port": 6379}]'
REDIS_SSL="True"
REDIS_AWS_IAM_AUTH="True"
REDIS_AWS_IAM_USER_NAME="litellm-cache"
REDIS_AWS_IAM_CACHE_NAME="litellm-cache"
REDIS_AWS_IAM_REGION="us-east-1"
REDIS_AWS_IAM_SERVERLESS="True"

5. 펼치고 검증하기

프록시를 통해 캐시를 ping 해보세요. 정상 응답은 SigV4 토큰이 서명되었고, ElastiCache가 수락했으며, 쓰기 왕복이 성공했음을 의미해요.

curl -s -X GET 'http://localhost:4000/cache/ping' \
  -H "Authorization: Bearer ***"

{
  "status": "healthy",
  "cache_type": "redis",
  "ping_response": true,
  "set_cache_response": "success"
}

그런 다음 같은 completion을 두 번 보내 캐시가 실제로 트래픽을 서빙하는지 확인하세요. 두 번째 호출은 같은 응답 id를 반환하고 훨씬 짧은 시간에 돌아와요.

curl -s -X POST 'http://localhost:4000/v1/chat/completions' \
  -H "Authorization: Bearer ***" \
  -H 'Content-Type: application/json' \
  -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "ping"}], "temperature": 0}'

설정 (Settings)

설정 필수 설명
aws_iam_auth 예 ElastiCache IAM 인증 켜기. bool 또는 truthy 문자열 받음
aws_iam_user_name 예 ElastiCache 사용자 이름. 사용자 id와 같아야 함
aws_iam_cache_name 예 서버리스 캐시 이름 또는 복제 그룹 id. 서명되므로 엔드포인트 호스트명이 아님
aws_iam_region 아니오 서명에 사용되는 리전. AWS_REGION, 그다음 AWS_DEFAULT_REGION으로 폴백
aws_iam_serverless 아니오 ElastiCache Serverless 캐시에서 설정. 서명된 요청에 ResourceType=ServerlessCache 추가

ssl: true는 이와 함께 필수예요. LiteLLM은 TLS 없이 IAM 인증을 켜거나 필수 설정이 빠지면 시작 시 예외를 발생시켜, 잘못된 구성이 부하 중 인증 실패가 되지 않고 즉시 드러나게 해요.

참고 사항 (Notes)

AWS 자격 증명은 표준 boto3 체인으로 해석되므로, IRSA, 인스턴스 프로파일, ECS 태스크 역할, AWS_PROFILE, 정적 키 모두가 추가 구성 없이 동작해요. LiteLLM은 스냅샷이 아니라 해석된 자격 증명 객체를 붙잡으므로, 장수 프록시에서 회전 자격 증명 소스가 계속 동작할 수 있어요.

AWS IAM과 함께 GCP IAM(gcp_service_account)이나 Azure AD(azure_redis_ad_token)를 구성하면 GCP나 Azure 경로가 우선하고 LiteLLM은 경고를 기록해요. 정확히 하나만 구성하세요.

자체 credential_provider를 제공하면 이 모두를 덮어써요. 이는 여전히 LiteLLM이 모델링하지 않는 인증 플로우용 탈출구예요.

문제 해결 (Troubleshooting)

  • AWS ElastiCache IAM Redis authentication requires TLS — cache_params에 ssl: true가 없거나, 제공한 url이 rediss:// 체계가 아닌 redis:// 체계를 사용한다는 뜻.
  • AWS ElastiCache IAM Redis authentication requires: <setting> — 빠뜨린 설정을 명명해요.
  • invalid username-password pair or user is disabled (Redis에서) — 토큰은 잘 형성됐지만 AWS가 거부했어요. 일반적인 원인은 캐시와 일치하지 않는 aws_iam_cache_name, 그 캐시에 연결된 사용자 그룹에 없는 사용자, 또는 캐시 ARN이나 사용자 ARN이 빠진 IAM 정책.
  • Unable to resolve AWS credentials for ElastiCache IAM Redis authentication — boto3 체인이 빈 채로 돌아왔으므로, pod에 역할이 없거나 환경에 자격 증명이 없다는 뜻.

함께 보기 (See also)

  • Redis 캐시의 나머지 모든 것(클러스터 토폴로지, 네임스페이스, TLS 포함)은 Redis and Valkey에 있어요.
  • Memorystore는 GCP Memorystore IAM Authentication을, Azure는 Azure Redis Entra ID Authentication을 보세요.