Operator / Admin — Confidential

LLM Gateway — 관리자 온보딩

🔒 이 문서는 배포한 관리자 1명만 열람하세요. LiteLLM 마스터 키·Langfuse 관리자 비밀번호 등 전체 관리자 자격이 평문으로 포함됩니다. 개발자에게 공유하거나 git에 커밋하지 마세요. 개발자에게는 developer-setup.html(시크릿 없음)을 배포하세요.

1 배포 요약 (엔드포인트 · 신원)

항목	값
게이트웨이 URL (개발자 base URL)	https://llmgw.example.com
LiteLLM Admin UI	https://llmgw.example.com/ui/
Token Service	https://abc123.execute-api.us-east-1.amazonaws.com/v1/auth/token
CloudWatch 사용량 대시보드	https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#dashboards:name=llmgw-dev-dashboard
Langfuse	https://langfuse.example.com
리전 / authMode / certMode	us-east-1 / cognito-native / acm

신원 (cognito-native)

Cognito User Pool ID	us-east-1_ABC123XYZ
App Client ID	1a2b3c4d5e6f7g8h9i0j
Hosted UI 도메인	llmgw-auth.auth.us-east-1.amazoncognito.com
Issuer	https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ABC123XYZ
Team Group Prefix	`llmgw-` (이 접두어 그룹 = LiteLLM 팀)

신원 (org-sso)

SSO Start URL	https://d-1234567890.awsapps.com/start
Account ID	111122223333
Permission Set / Role	LlmGatewayUser

2 시크릿 (실제값 — 취급 주의)

시크릿	값	보관 위치 (Secrets Manager)
LiteLLM 마스터 키 (Admin UI 로그인 = 전체 관리자)	sk-Xy9EXAMPLEmasterKEYdoNOTshare	llmgw-litellm-admin-key
Langfuse 관리자	admin@example.com / Adm1n-EXAMPLE-pw	llmgw-langfuse-admin

빠른 관리자 테스트(로그인 생략): 마스터 키를 직접 Bearer로 사용해 게이트웨이를 확인할 수 있습니다.

curl -s https://llmgw.example.com/v1/models -H "Authorization: Bearer sk-Xy9EXAMPLEmasterKEYdoNOTshare"

3 비밀번호 / 키 변경 방법

LiteLLM 마스터 키 회전

마스터 키는 Secrets Manager에 있고 컨테이너 시작 시 로드됩니다. 값 갱신 후 ECS 강제 재배포로 반영합니다.

aws secretsmanager put-secret-value \
  --secret-id llmgw-litellm-admin-key --secret-string 'sk-새로운마스터키'
aws ecs update-service --cluster llmgw-litellm --service litellm --force-new-deployment

개발자 가상 키는 별도 DB 레코드라 마스터 키 회전에 영향받지 않습니다. Admin UI 재로그인만 새 키로 하면 됩니다.

Langfuse 관리자 비밀번호

Langfuse UI 로그인 → Settings → Account 에서 변경이 가장 간단합니다. (초기값은 위 Secrets Manager 시드)

Cognito 사용자 비밀번호

# 관리자 강제 재설정
aws cognito-idp admin-set-user-password \
  --user-pool-id us-east-1_ABC123XYZ --username dev@example.com --password '새비밀번호' --permanent
# 사용자 셀프 재설정: Hosted UI의 "Forgot password"

4 개발자 온보딩 (관리자 작업)

cognito-native — 사용자 생성 + 팀 그룹 배정

aws cognito-idp admin-create-user --user-pool-id us-east-1_ABC123XYZ \
  --username dev@example.com --user-attributes Name=email,Value=dev@example.com \
  --desired-delivery-mediums EMAIL
aws cognito-idp admin-add-user-to-group --user-pool-id us-east-1_ABC123XYZ \
  --username dev@example.com --group-name llmgw-team1   # 그룹명 = LiteLLM 팀

org-sso — permission set 할당

IdC에서 해당 permission set을 사용자/그룹에 할당합니다. 신규 팀 = 신규 permission set + LiteLLM Admin UI 팀 설정(코드 재배포 불필요).

그다음 개발자에게 developer-setup.html 을 전달하면 끝입니다.

5 오프보딩 (접근 회수)

cognito-native

# 비활성(복구 가능) / 삭제 / 팀에서만 제거 중 택1
aws cognito-idp admin-disable-user --user-pool-id us-east-1_ABC123XYZ --username dev@example.com
aws cognito-idp admin-delete-user  --user-pool-id us-east-1_ABC123XYZ --username dev@example.com
aws cognito-idp admin-remove-user-from-group --user-pool-id us-east-1_ABC123XYZ --username dev@example.com --group-name llmgw-team1

org-sso

IdC에서 permission set 할당을 해제합니다.

⏱ 즉시 차단하려면 LiteLLM Admin UI에서 해당 가상 키를 revoke 하세요. 키는 DynamoDB 캐시에 TTL 동안 남아, revoke 없이는 로그인 차단 후에도 기존 키가 TTL 만료까지 동작할 수 있습니다.

6 운영 참고

팀/예산/모델 허용목록 조정 → LiteLLM Admin UI (https://llmgw.example.com/ui/, 마스터 키 로그인)
토큰 사용량·사용자별·시간대별 현황 → CloudWatch 사용량 대시보드 (https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#dashboards:name=llmgw-dev-dashboard: 모델/팀별 토큰·비용·지연, 사용자 Top-N, 시간대별 활동)
요청 로그/트레이스 → LiteLLM UI · Langfuse(활성 시) · CloudWatch
상세 운영: shared/reference/litellm-admin-guide.md
전체 teardown: cdk destroy (프로덕션은 RETAIN 정책 리소스 주의)

gen-onboarding.py 가 outputs.json + 관리자 자격증명으로 채운 문서입니다. 취급 주의.