AWS GenAI Lab

AWS Solution Skill · 사용 가이드

LLM Gateway Governance
Skill

AI(Kiro · Claude Code · Codex)와 대화하며, 사내 개발자용
LLM 거버넌스 게이트웨이를 AWS에 구축하는 Skill

LiteLLMAmazon BedrockAgentCore AWS CDK · TypeScriptSSO/Cognito · Guardrails · Data Residency

← / → · Space · 하단 버튼 · 점 클릭 으로 이동 — 총 24 슬라이드 · F 전체화면

무엇을 만드는가

한 문장 정의 + 4대 통제축

코드 에이전트(Claude Code · Codex)를 개별로 Bedrock에 붙이지 않고, 단일 거버넌스 게이트웨이를 강제 경유시켜 중앙 통제한다.

① 신원 · Who

신원 강제 — org-sso(AWSReservedSSO_) 또는 cognito-native(Cognito User Pool)
사용자별 가상키 발급
Enterprise 라이선스 불필요

② 모델·비용 · How much

모델 라우팅(Claude · GPT-5.6 Sol/Terra/Luna · 5.5 · 5.4)
티어별 allowlist
예산 캡(economy $50)

③ 콘텐츠 안전 · What

Bedrock Guardrails
콘텐츠·PII·금지토픽
시크릿 탐지(pre-call)

④ 관측·감사 · Trace

CloudWatch(인프라)
Langfuse(프롬프트/트레이스)
키별 사용량·예산

한 코드베이스로 최소 PoC ~ 엔터프라이즈까지 (토글로 구성)

아키텍처 다이어그램

VPC 격리 · ALB 엣지(certMode) · 엔드포인트로 프라이빗 Bedrock

👤 개발자Claude Code · Codex

→

🌐 공개 ALBacm=HTTPS / http=HTTP · SG 제한

→

🛡️ API GatewayIAM · SigV4 인증

→

λ Token Lambda신원 검증(SSO/Cognito) · 가상키

VPC · 2 AZ · 단일 리전 (예: ap-northeast-2 / us-east-1)

Public Subnet

NAT Gateway아웃바운드 egress

공개 ALB (certMode)

Private (egress)

Internal ALB인터넷 비노출

→

LiteLLMECS Fargate · Graviton

Token/DB-init λ

LangfuseECS(선택)

Interface Endpoints

Isolated Subnet

Aurora Serverless v2PostgreSQL · 저장 암호화 · 인터넷 격리

←

LiteLLM·Langfuse·λ 만 접근(SG)

AWS 서비스 — VPC 엔드포인트로 프라이빗 접근(인터넷 미경유)

Bedrock · Claude + Guardrail

Bedrock Mantle · GPT-5.6 / 5.5 / 5.4

AgentCore Gateway · Web Search Tool

Secrets Manager

DynamoDB · 키캐시

CloudWatch

S3 (Gateway EP)

PublicPrivate(egress)Isolated Claude/AgentCore = SigV4(Task Role, 토큰 없음) · Mantle = 런타임 발급 Bearer 키(BEDROCK_MANTLE_API_KEY)

배포 아키텍처 · AWS 아이콘

최종 배포 환경 — 전체 구성요소 (옵션 포함)

금색 점선 = 옵션 구성요소(Langfuse·certMode=acm·웹검색·GPT/Mantle·CodeBuild 이미지 빌드) · Claude/AgentCore = SigV4(Task Role, 토큰 없음) · Mantle = 런타임 발급 Bearer 키 · AWS 공식 아이콘

데이터 흐름 · 거버넌스 체크포인트

요청 1건이 거치는 통제 지점

거버넌스 · Governance

누가 · 무엇을 · 얼마나 · 어떻게 통제되는가

🪪 신원 (Identity)

두 모드: org-sso(IdC 조직 인스턴스, AWSReservedSSO_ ARN만 허용) 또는 cognito-native(계정 인스턴스/조직 SSO 불가 시 — Cognito User Pool이 유일 신원원, SAML/IdC 페더레이션 없음)

🔏 인가 (AuthZ)

org-sso: API GW AWS_IAM(SigV4), 권한셋 execute-api:Invoke만. cognito-native: API GW Cognito authorizer(scopes 없음 → id_token 수용, email claim 로깅), cognito:groups→팀

🔑 키 라이프사이클

사용자별 가상키 발급·DynamoDB 캐시(TTL). master key는 Secrets Manager grantRead. 장기 키 배포 없음

📊 티어링 · 예산

권한셋→LiteLLM 팀. economy=모델 allowlist + 예산 캡($50). standard=전 모델

🛡️ 정책 (Policy)

Bedrock Guardrail + 시크릿 탐지가 모든 Claude 요청에 default 적용. MCP는 키별 access group으로 스코프

🧾 감사 (Audit)

키별 사용량·예산, Langfuse 프롬프트/트레이스, CloudWatch 사용량 대시보드(모델·팀·사용자별 토큰/비용/지연 — EMF 자동 수집). cdk-nag 억제는 사유 명시

데이터 레지던시 · 네트워크 격리

데이터는 어디에 머무는가

📍 데이터 위치 (단일 리전 고정)

대화/키/사용량 → Aurora Serverless v2 (격리 서브넷, 저장 암호화) — 배포 리전 내
가상키 캐시 → DynamoDB (배포 리전, PITR)
시크릿 → Secrets Manager (배포 리전)
프롬프트/트레이스 → Langfuse → 동일 Aurora (리전 내)
모델 추론 → Bedrock (선택 리전 inference profile)
ALB idleTimeout → 기본 900s(최대 4000s) — 장시간 완성 흡수(CloudFront 120s 상한 제거)

🔒 격리 보장

인터넷 미경유 — Bedrock·Secrets·SSM·ECR·Logs·AgentCore를 VPC 인터페이스 엔드포인트로 호출
공개 ALB 엣지 — 두 모드 모두 인터넷 페이싱(acm=HTTPS:443, http=HTTP:80) · SG CIDR allowlist 제한, 내부 ALB는 Token Service 전용
DB 격리 — Aurora는 isolated 서브넷(egress 없음), SG로 LiteLLM/λ만 5432 허용
리전 고정 — 메인 스택 단일 리전(AgentCore/Mantle만 us-east-1)
S3/DynamoDB — Gateway 엔드포인트(무료, 리전 내)

데이터 레지던시 요건이 있으면 배포 리전을 고정하고 모든 영속 데이터가 그 리전에 머무름을 위 경로로 보장

가드레일 · Defense in Depth

요청마다 3계층 방어

Layer 1 · 시크릿 탐지

LiteLLM hide-secrets (pre-call) — API 키/토큰 패턴을 요청 단계에서 마스킹·차단. 모든 모델 공통

Layer 2 · Bedrock Guardrail

콘텐츠: HATE·INSULTS·SEXUAL·VIOLENCE·MISCONDUCT (HIGH)

PII 차단: 카드·SSN·AWS Access/Secret Key + API키 정규식

금지 토픽: 해킹툴·데이터 유출

Layer 3 · 도구(MCP) 스코프

가상키별 mcp_access_groups(예 default_tools). 팀 멤버십 없는 키는 도구 사용 불가 — 검색 트래픽도 게이트웨이 경유

⚠️ Bedrock Guardrail은 bedrock-runtime(Claude) 전용 → GPT(Mantle) 경로는 Layer 1로 보완하고 정책 공백을 문서화(constraints.md)

무엇을 선택하는가 · 7개 구성축

대화로 정하는 선택지

🌐

① 커스텀 도메인

📊

② 관측성 깊이

🎯

③ 모델·비용 티어

🤖

④ 제공 모델

🌏

⑤ 리전

💰

⑥ 용량·비용

🧱

⑦ 부트스트랩

#	선택축	config 필드	옵션
1	엣지 TLS	`litellm.certMode`	acm(도메인+ACM · HTTPS) / http(도메인X · HTTP 평문 · PoC 전용) — 둘 다 SG CIDR allowlist(`albIngressCidrs`) 필수
2	관측성 깊이	`enableLangfuse`	Langfuse on / CloudWatch만 — 어느 쪽이든 CloudWatch 사용량 대시보드(토큰·사용자별·시간대별)는 기본 제공
3	모델·비용 티어	Token Lambda 팀 매핑	standard(전 모델) / economy(allowlist + 예산캡)
4	제공 모델	`constants.MODELS`	Claude Opus/Sonnet/Haiku/Fable 5(bedrock-runtime) + GPT 5.6 Sol(플래그십·1M) / Terra(균형) / Luna(경제·저지연) · 5.5 · 5.4(bedrock_mantle) — 5.6는 LiteLLM `v1.98.0` 핀에서 정식 지원, 배포 후 Codex 스모크 테스트로 확인 후 개발자 온보딩
5	리전(데이터 레지던시)	`awsRegion`	config가 authoritative(constants 수정 불필요) · AgentCore/Mantle은 us-east-1 고정
6	용량·비용	`data.* · litellm.* · natGateways`	Aurora ACU · Fargate 크기 · NAT 수
7	부트스트랩	`bootstrapQualifier`	기본 / 커스텀(충돌 회피)

추가 토글: awsRegion(리전 선택) · guardrail.enabled · observability.dashboardEnabled · agentcore(AgentCore 웹검색) · mantle(GPT-5.6/5.5/5.4 피어링) · sso · auth.keyCacheTtlSeconds

어떻게 쓰는가 · 워크플로우

Discovery → Deploy, 게이트(GATE)로 확인하며 진행

1Discovery도메인·allowlist CIDR·모델·티어·관측성·리전·MCP·신원(+초기 사용자) 질의

2Designdecision-tree 적용 · MCP로 모델 ID/리전 검증

3GenerateCDK·Lambda·LiteLLM·스크립트 생성

4Validatetoolchain 정렬 · 이미지 CLI 사전검증 · typecheck · synth · cdk-nag

5Deploybootstrap(qualifier 확인) · cdk deploy · Mantle 워밍업 + GPT-5.6 Codex 스모크 테스트 · 온보딩 자동 실행

6OnboardingHTML 가이드 2종 생성(developer/admin, 항상 출력)

⛔ GATE 1 — 요구사항 확인

Discovery 답변 → config/dev.json 요약 승인. http 모드는 평문 전송 명시 승인(0.0.0.0/0이면 별도 승인) · cognito-native는 초기 사용자 · Fable/Mythos는 데이터 리텐션 opt-in 포함

⛔ GATE 2 — 아키텍처·비용 확인

스택 구성·예상 비용 제시 후 승인. MCP-first: 모델 ID는 하드코딩 금지·런타임 검증

근거: SKILL.md (Phase 1~6)

어떤 형태로 구축되는가 · 산출물

Skill이 생성하는 완성형 CDK 앱

project/ ├─ bin/app.ts # 10 스택 와이어링 ├─ config/dev.json # 선택값(런타임 검증) ├─ lib/ │ ├─ *-stack.ts # Network ~ Mantle │ ├─ interfaces.ts # cross-stack 계약 │ ├─ config/{constants,schema}.ts │ └─ nag-suppressions.ts ├─ lambda/ │ ├─ token-service/handler.py │ └─ db-init/handler.py ├─ services/litellm/ # config.yaml·Dockerfile └─ scripts/ · templates/ # 개발자 온보딩

IaC 전부 CDK — typecheck · synth · cdk-nag 게이트
Token Service — org-sso: API GW(IAM) / cognito-native: API GW(Cognito)+Lambda+DynamoDB
LiteLLM 컨테이너 — config.yaml · Mantle Bearer 토큰 콜백(aws-bedrock-token-generator, uv 설치)
개발자 온보딩 — setup-developer.sh가 outputs.json에서 전부 자동 유도(zero-touch) · 기존 사용자 설정은 병합·백업(덮어쓰기 금지) · 온보딩 HTML은 스크립트 실행 중심(수동 편집 안내 없음)
사용량 대시보드 — cloudwatch_usage EMF 콜백 + ObservabilityStack 대시보드(토큰·사용자별·시간대별·비용·지연)
테스트·억제 — synth 단언 · 정당화된 cdk-nag suppression

산업·티어·리전 입력에 맞춰 커스터마이즈되어 생성

내장된 베스트 프랙티스 · 함정 회피

실전에서 막히는 지점을 코드+문서로 예방

🌍 리전 하드코딩 금지

키 helper가 Token URL에서 SigV4 리전 파싱 → 무수정 다리전

🐳 pinned 이미지 사전검증

문서의 CLI 플래그도 docker run --entrypoint litellm <image> --help로 확인 — 미존재 플래그는 부팅 즉사(exitCode 2)

🧱 부트스트랩 충돌·qualifier

"no changes" ≠ 정상 — CDKToolkit의 실제 Qualifier 확인 후 cdk.json에 명시

🔗 SG 소유권 규칙

Network는 공용 인프라 SG만(CIDR ingress) · 서비스/ALB SG는 앱 스택 소유 → 순환참조 원천 차단

⚖️ Mantle ↔ Guardrail

Guardrail은 bedrock-runtime 전용 → GPT 경로 공백 명시

🔑 시크릿 외부화

master key·DB·앱 시크릿은 Secrets Manager. 평문은 안티패턴

🔀 사용자 설정 병합

~/.claude·~/.codex는 공유 파일 — 백업 후 우리 키만 갱신, 절대 덮어쓰지 않음

🔁 UI 리다이렉트

PROXY_BASE_URL/NEXTAUTH_URL=공개 URL 단독 메커니즘 (--forwarded-allow-ips는 이미지에 없음 — 금지)

🏗️ prod 전환 체크

RETAIN·백업·per-AZ NAT·스코프 IAM·로그 — 각 항목 PROD TODO

🕳️ addListener 0.0.0.0/0

CDK 기본 open:true가 SG allowlist 옆에 전세계 오픈 규칙을 조용히 추가 → 모든 리스너에 open:false + 배포 후 SG 실사

🧪 GPT-5.6 스모크 테스트

5.6 Sol/Terra/Luna 정식 지원 — LiteLLM v1.98.0 핀에 5.6 라우팅 포함(v1.93.0부터 stable), Mantle도 Codex namespace 툴 타입을 서버 측에서 수용. 배포 후 멀티턴·툴 사용 Codex 세션 1회로 확인하고 온보딩(5.5/5.4는 폴백 페어)

📐 메트릭 카디널리티

EMF 디멘전은 Model/Team(유한)만 — 사용자는 property(무한 집합=메트릭 과금 폭발). 사용자별 뷰는 Logs Insights. SEARCH 범례엔 dynamic label 필수

근거: shared/reference/constraints.md (실 배포에서 발견·역반영된 항목)

전제조건 · Discovery 전에 확인할 것들

배포 시작 전 계정 · 권한 · 신원(SSO/Cognito) 준비

☁️ AWS 계정 · 권한

대상 계정에 VPC/ECS/RDS/Lambda/APIGW/ALB/ACM/IAM 생성 권한
게이트웨이 리전 + us-east-1 양쪽 모두 cdk bootstrap 가능
Bedrock 모델 액세스 활성화 — Claude(게이트웨이 리전), GPT-5.6 Sol/Terra/Luna · 5.5 · 5.4/Mantle(us-east-1)
AWS Marketplace 구독 가능(Mantle 첫 호출 자동 구독)

🪪 org-sso 경로 — IAM Identity Center (이 경로를 쓸 때만)

Token Service가 AWSReservedSSO_ 신원만 허용(org-sso). 조직 SSO가 없으면 cognito-native를 선택 — 아래 IdC 준비는 불필요
IdC 활성화 여부 · 리전 확인
자격 소스: 내장 디렉터리 / 외부 IdP(Okta·Entra)
배정할 그룹 또는 사용자 존재 여부(팀 권장) — 미비 시 GATE 1에서 즉시 블로커로 표기

🔎 org-sso 1회 준비 절차 (cognito-native는 해당 없음)

1권한세트 생성이름에 밑줄 금지 · execute-api:Invoke only

2계정 할당사용자/그룹 → 계정

3사용자 생성identitystore (또는 기존 사용)

4비밀번호 활성화IdC 콘솔 전용 · 핸드오프

5로그인org-sso aws sso login · cognito llmgw-login

근거: shared/reference/prerequisites.md · shared/reference/sso-setup.md — 로컬 툴체인(Docker/Node/CDK/AWS CLI) 설치는 다음 슬라이드

전제조건 · 로컬 툴체인 설치

Docker(권장) · Node · CDK · AWS CLI — OS별 설치 + 확인

🍎 macOS — zsh

# 1) Docker Desktop 설치 (권장 — 없으면 imageBuild.mode='codebuild') $ brew install --cask docker # 설치 후 Applications에서 Docker.app 1회 실행 → 데몬 기동 # 2) Node.js 20 LTS $ brew install node@20 # 또는 nvm 사용 시: $ nvm install 20 && nvm use 20 # 3) AWS CDK CLI v2 $ npm install -g aws-cdk # 4) AWS CLI v2 + jq $ brew install awscli jq # ── 설치 확인 ────────────────────── $ docker info | head -1 Client: Docker Desktop $ node -v v20.18.1 $ cdk --version 2.170.0 (build abcd123) $ aws --version aws-cli/2.22.9 Python/3.13.1 Darwin/24.1.0 ✅ 4개 모두 출력되면 준비 완료

🐧 Linux — bash (Ubuntu/Debian)

# 1) Docker Engine (배포판 docker.io는 구버전이라 비권장) # 공식 가이드: docs.docker.com/engine/install/ubuntu $ curl -fsSL https://get.docker.com -o get-docker.sh $ sudo sh get-docker.sh $ sudo usermod -aG docker $USER # 재로그인 필요 $ sudo systemctl enable --now docker # 2) Node.js 20 (nvm 권장 — 배포판 패키지는 구버전) $ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash $ source ~/.bashrc && nvm install 20 # 3) AWS CDK CLI v2 $ npm install -g aws-cdk # 4) AWS CLI v2 (x86_64 / --linux-aarch64.zip on ARM) $ curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o awscliv2.zip $ unzip awscliv2.zip && sudo ./aws/install $ sudo apt-get update && sudo apt-get install -y jq # ── 설치 확인 ────────────────────── $ docker info | head -1 Client: Docker Engine - Community $ node -v && cdk --version && aws --version v20.18.1 2.170.0 (build abcd123) aws-cli/2.22.9 Python/3.13.1 Linux/6.8.0 ✅ 4개 모두 출력되면 준비 완료

🪟 Windows — PowerShell / WSL2

# 권장: WSL2 안에서 위 Linux 절차 그대로 실행 PS> wsl --install # 관리자 PowerShell, 재부팅 후 PS> wsl --status 기본 배포판: Ubuntu ... # Docker Desktop (WSL2 엔진 필수 — 아래는 native PowerShell 경로) # 1) docker.com/products/docker-desktop 설치 후 # Settings → General → "Use the WSL 2 based engine" 체크 # Settings → Resources → WSL Integration → 배포판 활성화 # 2) Node.js 20 LTS PS> winget install OpenJS.NodeJS.LTS # 3) AWS CDK CLI v2 (WSL·PowerShell 중 실제 배포할 셸에서) PS> npm install -g aws-cdk # 4) AWS CLI v2 + jq PS> winget install Amazon.AWSCLI PS> winget install jqlang.jq # ── 설치 확인 ────────────────────── PS> docker info Client: Docker Desktop 4.x (WSL2 backend) PS> node -v; cdk --version; aws --version v20.18.1 2.170.0 (build abcd123) aws-cli/2.22.9 Python/3.13.1 Windows/10 ✅ 4개 모두 출력되면 준비 완료 ⚠️ WSL과 PowerShell을 섞지 말 것 — cdk deploy를 실행할 셸 한쪽에만 설치

스크롤하여 전체 출력 확인 · Docker는 권장(없으면 CodeBuild 빌드) · Node · CDK · AWS CLI가 ❌면 Phase 1 Discovery 진행 금지 · 근거: shared/reference/prerequisites.md §1

설치 · 3개 도구 공통

한 SKILL.md, 세 곳에 설치

Kiro

~/.kiro/skills/
llm-gateway-governance

Claude Code

~/.claude/skills/
llm-gateway-governance

Codex

~/.agents/skills/
llm-gateway-governance

세 곳의 SKILL.md는 md5 동일(CI 검증) · 지식은 shared/에 1벌만 작성(sync-skills.sh).

Codex: npm install -g @openai/codex · developers.openai.com/codex

트리거 예: "사내 개발자용 LLM 게이트웨이 만들어줘" · "Govern Bedrock access for developers"

설치 후 SKILL.md description으로 자동 활성화(트리거 매칭)

배포 후 운영 · LiteLLM Admin Ops (1/2)

배포 이후 운영자가 하는 일

🔐 Admin UI 로그인

<gateway-url>/ui/ (acm=https:// · http=http://)
자격증명은 master key 단 하나 — Secrets Manager에서 조회(CDK 출력·로그에 절대 노출 안 함)
developer는 master key 불필요 — 로그인(SSO 또는 Cognito)으로 받은 가상키만 사용

👥 팀·사용자 생성 (SSO/Cognito 매핑)

자동 경로(기본): org-sso 권한세트(또는 cognito-native Cognito 그룹) 로그인 → Token Lambda가 그 이름과 동일한 team_alias로 lookup-or-create (1:1 무분기 매칭)
수동 경로: UI Teams → + New Team 또는 POST /team/new로 선점 생성 — team_alias를 권한세트명과 동일하게 입력
team_alias는 권한세트명 자체와 정확히 일치해야 함 — 오타 시 의도한 팀이 아닌 별도 팀으로 조용히 연결됨

이후 자주 쓰는 4가지 Admin UI 작업(모델 설정·예산·프롬프트 확인·사용량)은 다음 슬라이드 · 근거: shared/reference/litellm-admin-guide.md

배포 후 운영 · LiteLLM Admin Ops (2/2)

자주 쓰는 4가지 Admin UI 작업

1️⃣ 모델 설정 (Bedrock 포함)

Admin UI → Models → Add Model → model_name, litellm_params 입력

Model 관리: docs.litellm.ai/docs/proxy/model_management

Bedrock 전용 파라미터(model prefix, AWS credentials 등): docs.litellm.ai/docs/providers/bedrock

2️⃣ 사용자별 예산 지정

Admin UI → Internal Users → 사용자 선택 → max_budget, budget_duration 설정

가이드: docs.litellm.ai/docs/proxy/users

Team budget(공유 pool)과는 다른 스코프 — 개인별 cap이 필요하면 이 경로 사용

3️⃣ 사용자 프롬프트(요청/응답) 확인

Admin UI → Logs → Settings(⚙️) → "Store Prompts in Spend Logs" 활성화 → Save (재시작 불필요)

설정: docs.litellm.ai/docs/proxy/ui_spend_log_settings

로그 조회 전반: docs.litellm.ai/docs/proxy/ui_logs

4️⃣ 사용자별 사용량 확인

Admin UI → Usage → Customer Usage 탭 → 고객별 spend, 일별 추이, 모델별 사용 비중 확인 · 인프라 한눈 뷰는 CloudWatch 사용량 대시보드(다음 슬라이드)

Customer Usage: docs.litellm.ai/docs/proxy/customer_usage

Spend Tracking 전반: docs.litellm.ai/docs/proxy/cost_tracking

근거: shared/reference/litellm-admin-guide.md §5 · Enterprise 라이선스 불필요(Admin UI·팀·budget 모두 OSS 기능)

배포 후 운영 · CloudWatch 사용량 대시보드

토큰 · 사용자 · 시간 — 배포와 함께 생기는 대시보드

⚙️ 동작 원리 — EMF 한 줄이 전부

cloudwatch_usage 콜백이 요청마다 EMF JSON 한 줄을 stdout에 출력 → 기존 awslogs 파이프라인 → CloudWatch가 메트릭 자동 추출. 추가 IAM 없음 · API 호출 없음 · 요청 경로 오버헤드 없음

📐 설계 규칙

디멘전=Model/Team(유한 집합, 그래프용) · 사용자=property(무한 집합 — Logs Insights로 조회, 메트릭 과금 0). 사용자별 이력은 로그 보존(2주) 한도 — 장기 리포트는 LiteLLM Admin UI/DB

🔎 배포 직후 검증

테스트 호출 1건 → 로그에 "llmgw":"usage" 라인 → ~2분 내 list-metrics에 TotalTokens → DashboardUrl 출력값 열기

위젯	보여주는 것
토큰 by 모델/팀	TotalTokens 합계 추이 (SEARCH로 런타임 생성 팀 자동 발견)
Prompt vs Completion	모델별 입·출력 토큰 분리
비용(USD) by 팀	LiteLLM 자체 비용 계산치 합계
요청/실패 · 지연	모델별 Requests·Failures, LatencyMs avg/p99
사용자 Top-N	토큰·요청·비용 상위 20명 테이블 (Logs Insights)
시간대별 사용	시간별 토큰·요청·활성 사용자 수
사용자×모델 드릴다운	누가 어떤 모델을 얼마나 (상위 50행)
ALB 상태	requests · 5xx · target p95

ObservabilityStack(dashboardEnabled) · DashboardUrl CfnOutput · 근거: shared/patterns/cdk-stacks.md §7 · litellm-gateway.md §4 · 실 배포 검증(60개 시계열 자동 추출 확인)

배포 후 운영 · org-sso 사용자·그룹 → LiteLLM 권한/예산

org-sso 온보딩 — IdC + Admin UI만으로 반복 가능

✅ 관리자가 알아야 할 결론

이 스킬로 생성된 게이트웨이는 기본값부터 권한세트명 = LiteLLM team_alias로 1:1 매칭되도록 코드가 생성됩니다. 그래서 새 조직·팀이 생겨도 개발자 개입·코드 수정·재배포 없이, IdC 콘솔 + LiteLLM Admin UI 클릭만으로 온보딩·예산변경·모델 제한이 끝납니다.

IdC에서 사용자 추가

IAM Identity Center 콘솔 → Users → Add user — 이미 있는 사용자면 스킵

사용자 생성

IdC에서 그룹 추가 + 사용자 배정

IdC 콘솔 → Groups → Create group (팀명 그대로, 예: team-research) → Add users to group

그룹 구성

권한세트 생성 + 계정 할당

IdC 콘솔 → Permission sets → Create, 그룹과 동일한 이름(밑줄 금지) → execute-api:Invoke-only 정책 → AWS accounts에서 그룹에 배정

IAM 매핑

LiteLLM Admin UI에서 팀 생성 + 예산·모델 설정

Admin UI → Teams → + New Team, team_alias = 3번과 동일한 이름 → Models(allowlist), Max Budget/Budget Duration을 화면에서 직접 입력 — 코드/배포 없음

권한·예산 확정

비밀번호 활성화 + 검증

IdC 콘솔(전용) → Reset password → 사용자가 aws sso login 후 첫 호출 시 Admin UI Teams에서 반영 확인

활성화·확인

🔧 권한세트명과 team명이 같아야 하는 이유

이 스킬이 생성하는 Token Lambda(_resolve_team_id)는 권한세트명을 그대로 LiteLLM team_alias로 사용합니다 — 별도의 매핑 테이블이나 if/else 분기가 없습니다. 그래서 3번(권한세트)과 4번(LiteLLM 팀)의 이름을 다르게 지으면 그 그룹의 로그인은 엉뚱한(또는 새로) 팀으로 연결되어 의도한 예산·모델 제한이 적용되지 않습니다. 이름을 똑같이 맞추는 것 자체가 유일한 연결 고리이므로, 온보딩 때마다 3·4번의 이름 일치만 지키면 코드를 열어볼 일이 없습니다.

잊지 말 것: 4번을 건너뛰면 조용히 default team으로 빠져 예산·allowlist가 적용 안 됨 · 근거: shared/patterns/lambda-handlers.md · shared/reference/sso-setup.md · shared/reference/litellm-admin-guide.md §2

배포 후 운영 · cognito-native 사용자·그룹 → LiteLLM 권한/예산

cognito-native 온보딩 — Cognito + Admin UI만으로 (조직 SSO 불필요)

✅ 관리자가 알아야 할 결론

조직 SSO를 못 쓰는 환경(IdC 계정 인스턴스 등)에서도 Cognito User Pool Group명 = LiteLLM team_alias로 1:1 매칭되도록 코드가 생성됩니다. IdC·permission set 없이, Cognito 콘솔·CLI + LiteLLM Admin UI 클릭만으로 온보딩·예산변경·모델 제한이 끝납니다.

Cognito 사용자 생성

Cognito가 유일 신원원(self-signup off) — 첫 사용자는 배포 시 에이전트가 자동 생성(Discovery 답변 기반, 풀은 0명으로 배포됨). 추가는 aws cognito-idp admin-create-user --user-pool-id <pool> --username dev@ex.com (또는 콘솔)

사용자 생성

User Pool Group 생성 + 사용자 추가

Group명 = 팀(teamGroupPrefix 접두어, 예 llmgw-team-research) → admin-add-user-to-group. IdC permission set 불필요

그룹 구성

cognito:groups 자동 반영

로그인 시 access token에 그룹이 실려 Token Lambda가 teamGroupPrefix로 필터해 팀 결정 — 별도 IAM·Identity Store 호출 없음

신원→팀

LiteLLM Admin UI에서 팀 생성 + 예산·모델 설정

Admin UI → Teams → + New Team, team_alias = 2번 Group명과 동일 → Models(allowlist)·Max Budget을 화면에서 직접 입력 — 코드/배포 없음

권한·예산 확정

비밀번호 설정 + 검증

admin-set-user-password --permanent(또는 첫 로그인 강제변경) → 사용자가 llmgw-login(Cognito Hosted UI) 후 Admin UI Teams에서 반영 확인

활성화·확인

🔧 Group명 = team_alias가 같아야 하는 이유

Token Lambda(_resolve_team_id)는 검증된 cognito:groups 중 teamGroupPrefix에 맞는 하나를 그대로 team_alias로 씁니다(require-single-team-group: 0개·다중이면 거부). Identity Store 호출·매핑 테이블·if/else 분기 없음 — 2번 Group명과 4번 team_alias가 다르면 엉뚱한 팀으로 연결됩니다. ⚠️ 클라이언트는 id_token을 보냅니다(access token엔 email claim이 없어 로그가 sub UUID로 찍힘; authorizer는 authorizationScopes 없이 id_token 수용).

org-sso 대비: permission set → Cognito User Pool Group · aws sso login → llmgw-login · 근거: shared/reference/account-instance-setup.md · shared/patterns/lambda-handlers.md · shared/reference/litellm-admin-guide.md

배포 후 운영 · 개발자 온보딩 (Claude Code + Codex 클라이언트)

개발자 온보딩 — setup 한 번이면 클코·코덱스 동시 연결

🚀 한 번에 끝 (제로터치)

scripts/setup-developer.sh (Windows: .ps1 / py -3 gateway_auth.py setup) — outputs.json에서 게이트웨이 URL·모델 별칭·인증모드 자동 도출
~/.claude/settings.json + ~/.codex/config.toml을 병합(백업 후 우리 키만 수정 — hooks·플러그인 보존)
이후 로그인: org-sso aws sso login(IdC 세션 8h) / cognito llmgw-login(refresh 30d)

🧹 병합이 "지우는" 것 (실사고 2건)

직접호출 잔재 CLAUDE_CODE_USE_BEDROCK·AWS_BEARER_TOKEN_BEDROCK 제거 — 남으면 두 인증 경로 충돌 → 403 "API key not valid"
최상위 model(raw Bedrock ID) 제거 — 별칭보다 우선 적용돼 "team not allowed to access model"

⚙️ Codex 특칙 (실사고 2건)

auth는 command(실행파일)+args(배열) 분리 — Codex는 셸 없이 spawn, 합친 문자열은 401 "No api key"
web_search = "disabled" 필수 — Mantle이 web_search 툴 거부 → "high demand" 오표시 루프. 검색은 게이트웨이 AgentCore MCP로

🔑 인증 체감 — 개발자는 로그인만

가상키는 1시간마다 자동 회전 — apiKeyHelper/auth.command가 만료 시 조용히 재발급, 개발자 무감
재로그인 주기는 IdP 세션이 결정(키 duration과 무관) — 짧은 키 수명은 보안 창만 좁힘
검증: healthcheck → /v1/models에서 별칭 목록 확인

근거: shared/patterns/developer-onboarding.md · shared/reference/constraints.md "Cross-platform client onboarding" · 실배포(Windows 포함) 검증

배포 후 운영 · 오프보딩 (권한 회수)

오프보딩 — IdP 제거만으로는 안 끊긴다

⚠️ 핵심 사실

SSO/Cognito는 가상키의 발급만 통제합니다. IdC에서 사용자를 지워도(또는 SSO 세션이 만료돼도) 이미 발급된 가상키는 만료 시점까지 동작 — 이 게이트웨이는 키를 1시간 만료로 발급하므로 잔존 창 ≤ 1시간, 즉시 차단은 LiteLLM revoke가 유일합니다. (duration 없이 발급하던 과거 배포는 무기한 — 반드시 revoke)

LiteLLM 가상키 revoke — 즉시 차단

Admin UI → Virtual Keys → 별칭(sso-…/cognito-…) 삭제, 또는 POST /key/delete {"key_aliases":[…]} (master key) · 복귀 가능성 있으면 /key/block(정지)

차단 완료

재발급 차단 — IdP에서 제거

org-sso: IdC 그룹/계정 할당 제거 · cognito: admin-disable-user(+admin-user-global-sign-out) — 이제 새 키를 받을 수 없음

재발급 차단

정리·확인

DynamoDB 키캐시 항목(USER#…) 삭제(위생) → Admin UI Logs/CloudWatch에서 해당 user_id 요청이 멈췄는지 확인

감사 확인

자격증명	수명	즉시 회수 방법
SSO 세션 (org-sso)	IdC 기본 8h	자동 만료 (발급 관문만 잠김)
Cognito access / refresh	1h / 30d	`admin-user-global-sign-out`
LiteLLM 가상키	1h 자동 만료·회전	`/key/delete` · `/key/block` (Admin UI)
master key	무기한	Secrets Manager 회전 + ECS 재배포

순서가 중요: ①revoke 먼저(즉시) → ②IdP 제거(재발급 차단) · 근거: shared/reference/litellm-admin-guide.md §6 Offboarding · constraints.md "Virtual-key lifetime ≠ SSO session" · 실배포에서 1h 자동회전 검증(2026-07)

검증된 자산 · 실제 배포 결과

레퍼런스는 실제 배포·검증됨

10개 스택 전부 CREATE_COMPLETE
ECS LiteLLM·Langfuse 1/1 running
공개 ALB → LiteLLM /health 200
신원 강제 org-sso: 비-SSO 호출 403 / cognito: JWT 검증 (설계대로)
SSO 사용자 발급 → 가상키 → Claude 정상 응답
UI LiteLLM·Langfuse 로그인 동작(도메인리스)

10/10

스택 배포

3계층

Guardrail

저장 시크릿(장기)

3툴

md5 동일 SKILL

실 배포에서 발견한 이슈(SG 순환참조·미존재 CLI 플래그·bootstrap qualifier·설정 덮어쓰기·stale config 등)는 모두 Skill에 역반영

시작하기

이렇게 말하면 됩니다

"사내 개발자용 LLM 게이트웨이 만들어줘"

"Govern Bedrock access for developers" · "LiteLLM 배포하고 SSO/Cognito 가상키 발급"

DiscoveryDesignGenerate ValidateDeployOnboarding

⬇ 스킬 다운로드 (.zip)

llm-gw.genailab.daradat.cloud/llm-gateway-governance-skill.zip

AWS GenAI Lab · llm-gateway-governance-skill · Kiro · Claude Code · Codex

LLM Gateway GovernanceSkill

한 문장 정의 + 4대 통제축

① 신원 · Who

② 모델·비용 · How much

③ 콘텐츠 안전 · What

④ 관측·감사 · Trace

VPC 격리 · ALB 엣지(certMode) · 엔드포인트로 프라이빗 Bedrock

최종 배포 환경 — 전체 구성요소 (옵션 포함)

요청 1건이 거치는 통제 지점

누가 · 무엇을 · 얼마나 · 어떻게 통제되는가

🪪 신원 (Identity)

🔏 인가 (AuthZ)

🔑 키 라이프사이클

📊 티어링 · 예산

🛡️ 정책 (Policy)

🧾 감사 (Audit)

데이터는 어디에 머무는가

📍 데이터 위치 (단일 리전 고정)

🔒 격리 보장

요청마다 3계층 방어

Layer 1 · 시크릿 탐지

Layer 2 · Bedrock Guardrail

Layer 3 · 도구(MCP) 스코프

대화로 정하는 선택지

① 커스텀 도메인

② 관측성 깊이

③ 모델·비용 티어

④ 제공 모델

⑤ 리전

⑥ 용량·비용

⑦ 부트스트랩

Discovery → Deploy, 게이트(GATE)로 확인하며 진행

⛔ GATE 1 — 요구사항 확인

⛔ GATE 2 — 아키텍처·비용 확인

Skill이 생성하는 완성형 CDK 앱

실전에서 막히는 지점을 코드+문서로 예방

🌍 리전 하드코딩 금지

🐳 pinned 이미지 사전검증

🧱 부트스트랩 충돌·qualifier

🔗 SG 소유권 규칙

⚖️ Mantle ↔ Guardrail

🔑 시크릿 외부화

🔀 사용자 설정 병합

🔁 UI 리다이렉트

🏗️ prod 전환 체크

🕳️ addListener 0.0.0.0/0

🧪 GPT-5.6 스모크 테스트

📐 메트릭 카디널리티

배포 시작 전 계정 · 권한 · 신원(SSO/Cognito) 준비

☁️ AWS 계정 · 권한

🪪 org-sso 경로 — IAM Identity Center (이 경로를 쓸 때만)

🔎 org-sso 1회 준비 절차 (cognito-native는 해당 없음)

Docker(권장) · Node · CDK · AWS CLI — OS별 설치 + 확인

한 SKILL.md, 세 곳에 설치

Kiro

Claude Code

Codex

배포 이후 운영자가 하는 일

🔐 Admin UI 로그인

👥 팀·사용자 생성 (SSO/Cognito 매핑)

자주 쓰는 4가지 Admin UI 작업

1️⃣ 모델 설정 (Bedrock 포함)

2️⃣ 사용자별 예산 지정

3️⃣ 사용자 프롬프트(요청/응답) 확인

4️⃣ 사용자별 사용량 확인

토큰 · 사용자 · 시간 — 배포와 함께 생기는 대시보드

⚙️ 동작 원리 — EMF 한 줄이 전부

📐 설계 규칙

🔎 배포 직후 검증

org-sso 온보딩 — IdC + Admin UI만으로 반복 가능

✅ 관리자가 알아야 할 결론

🔧 권한세트명과 team명이 같아야 하는 이유

cognito-native 온보딩 — Cognito + Admin UI만으로 (조직 SSO 불필요)

✅ 관리자가 알아야 할 결론

🔧 Group명 = team_alias가 같아야 하는 이유

개발자 온보딩 — setup 한 번이면 클코·코덱스 동시 연결

🚀 한 번에 끝 (제로터치)

🧹 병합이 "지우는" 것 (실사고 2건)

⚙️ Codex 특칙 (실사고 2건)

🔑 인증 체감 — 개발자는 로그인만

LLM Gateway Governance
Skill