projects/awsome-ai-gateway · ARCHITECTURE.md 기준

AWSome AI Gateway 아키텍처

Claude Code, Codex, Cowork는 OIDC로 로그인한 뒤 Virtual Key(VK) 하나로 게이트웨이를 호출합니다. 게이트웨이는 사용자·팀 예산과 Rate Limit을 확인하고, routing_profiles 테이블에 따라 클라이언트별로 다른 계정·리전의 Bedrock으로 요청을 보냅니다. 비용은 응답 경로를 막지 않도록 Redis Stream을 거쳐 비동기로 Aurora에 쌓입니다.

발표자료 PDF 보기 PPTX 다운로드 (4.2MB)

시스템 구성

개발자 PC Claude Code Codex Cowork gateway-cli api-key-helper 운영자 브라우저 메인 계정 · ap-northeast-2 Amazon Cognito OIDC IdP · 로컬은 Keycloak EKS Fargate · Helm llm-gateway gateway-proxy 데이터 플레인 · FastAPI ClientId → Auth(VK) → ClientAuthZ → Budget → Downgrade → RateLimit → router routing_profiles 테이블로 client별 백엔드 선택 (Redis 캐시 300s) scheduler ROI 집계 · VK 만료 notification-worker 예산 임계값 알림 cost-recorder worker · 배치 적재 admin-ui Next.js 14 대시보드 admin-api VK 발급 · 거버넌스 CRUD AgentCore Runtime BI 에이전트 · Strands query_db Lambda (RO) Aurora PostgreSQL 사용자 · 키 · 예산 · 사용량 usage_logs ElastiCache Valkey VK 캐시 · RateLimit cost:stream Secrets Manager → ESO · KMS · CloudWatch · CloudTrail · ECR claude-code Bedrock native · invoke_model Claude Code 계정 · ap-northeast-2 STS AssumeRole · 실패 시 메인 계정 폴백 codex Bedrock Mantle · OpenAI Responses 메인 계정 · us-east-2 GPT-5.5 · IRSA 직접 (assume 없음) cowork Bedrock Mantle · Anthropic Messages Cowork 계정 · ap-northeast-1 Opus 4.8 · STS AssumeRole 서버사이드 웹서치 AgentCore Gateway · WebSearch 메인 계정 · us-east-1 routing profile 옵션 · 기본 off Bearer VK OIDC 로그인 (PKCE) id_token → VK 교환 HTTPS SigV4 · SSE CRUD VK 조회 · RL XREADGROUP usage_logs 적재
gateway-proxy 하나가 세 클라이언트의 요청을 받아, 각각 다른 계정·리전의 Bedrock으로 보냅니다(파란 선). cross-account 호출은 STS AssumeRole을 쓰고, claude-code는 AssumeRole이 실패해도 메인 계정 Bedrock으로 투명하게 폴백합니다. 운영자는 admin-ui → admin-api로 관리하며, admin-api는 Cognito JWKS로 id_token을 검증한 뒤 VK를 발급합니다.
추론 요청 경로 인증 · 관리 · 조회 비동기 비용 기록

요청 한 건의 흐름

VK 발급은 최초 로그인이나 VK 만료 때만 일어납니다. 그 뒤 호출에서 게이트웨이는 DB를 거치지 않고 Valkey에서 VK와 예산을 확인합니다. 비용은 응답이 끝날 때 스트림에 한 줄을 넣는 것(약 1–2ms)으로 끝나고, Aurora 적재는 cost-recorder가 배치로 처리합니다.

VK 발급 최초 로그인 · 만료 시 추론 호출 매 요청 비용 기록 응답과 분리 · 비동기 클라이언트 Cognito admin-api gateway-proxy Valkey Bedrock cost-recorder Aurora 1 OIDC PKCE 로그인 2 id_token 3 POST /v1/auth/exchange 4 JWKS 검증 → 사용자 · 팀 자동 프로비저닝 (신규 팀 예산 $0) 5 Virtual Key 6 /v1/messages · Bearer VK 7 VK·예산·RL 8 routing_profile 대상 호출 9 응답 (SSE) 10 스트림 전달 11 XADD 12 XREADGROUP 배치 13 usage_logs
4단계에서 자동 생성된 팀은 예산이 $0(HARD_BLOCK)이라, 관리자가 예산을 배정하기 전까지 7단계에서 429로 막힙니다. Claude Code는 429를 조용히 재시도하므로 사용자에게는 응답이 멈춘 것처럼 보입니다.

AWS 배포와 이 EC2의 로컬 구성

지금 이 EC2에 올라가 있는 docker-compose 환경은 같은 서비스 코드를 쓰고, 관리형 서비스만 컨테이너로 바꿔 둔 구성입니다.

구성 요소AWS 배포이 EC2 (docker-compose)
실행 환경EKS Fargate · Helm (6 Deployment + migration Job)docker compose 컨테이너
IdPAmazon CognitoKeycloak :8088 · realm dslg
DBAurora PostgreSQLpgvector/pg16 :5432
캐시 · 스트림ElastiCache ValkeyRedis :6379
Bedrock 자격증명워크로드별 IRSA + STS AssumeRoleEC2 인스턴스 역할 · cross-account 실패 시 in-account 폴백
관측CloudWatch · CloudTrailOTel Collector · Prometheus · Loki · Grafana :3001
BI 에이전트AgentCore Runtime구성하지 않음
접속ALB Ingressgateway :8000 · admin-api :8080 · admin-ui /absproxy/3000/

출처: 레포의 ARCHITECTURE.md와 README.md. 계정 ID는 문서의 placeholder 대신 역할 이름(메인 · Claude Code · Cowork 계정)으로 표기했습니다.