AWS Solution Skill · 사용 가이드

LLM Gateway Governance
Skill

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

LiteLLMAmazon BedrockAgentCore AWS CDK · TypeScriptSSO · Guardrails · Data Residency

← / → · Space · 하단 버튼 · 점 클릭 으로 이동 — 총 15 슬라이드

무엇을 만드는가

한 문장 정의 + 4대 통제축

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

① 신원 · Who

SSO 신원 강제(AWSReservedSSO_)
사용자별 가상키 발급
Enterprise 라이선스 불필요

② 모델·비용 · How much

모델 라우팅(Claude/GPT)
티어별 allowlist
예산 캡(economy $50)

③ 콘텐츠 안전 · What

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

④ 관측·감사 · Trace

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

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

아키텍처 다이어그램

VPC 격리 · CloudFront 단일 진입 · 엔드포인트로 프라이빗 Bedrock

👤 개발자Claude Code · Codex
→
☁️ CloudFrontTLS 종단 · VPC Origin
→
🛡️ API GatewayIAM · SigV4 인증
→
λ Token LambdaSSO 검증 · 가상키
VPC · 2 AZ · 단일 리전 (예: ap-northeast-2 / us-east-1)
Public Subnet
NAT Gateway아웃바운드 egress
·
CloudFront VPC Origin 진입
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
AgentCore Runtime · Tavily MCP
Secrets Manager
DynamoDB · 키캐시
CloudWatch
S3 (Gateway EP)
PublicPrivate(egress)Isolated SigV4(Task Role) — Bedrock/Mantle/AgentCore 호출에 토큰 없음
각 컴포넌트가 하는 일

8개 스택 · 책임 분리

Network

VPC·3계층 서브넷, SG 체인(누가 누구에게 어떤 포트), Gateway/Interface 엔드포인트로 트래픽 VPC 내 유지

Data

Aurora Serverless v2(격리 서브넷·암호화). LiteLLM/Langfuse DB 시크릿 분리 + db-init 커스텀 리소스

Guardrail

Bedrock Guardrail 생성: 콘텐츠 필터·PII 차단·금지 토픽. LiteLLM이 ID/버전으로 참조

LiteLLM

게이트웨이 본체. ECS Fargate(Graviton)+내부 ALB. Task Role SigV4로 Bedrock 호출. master key 소유

Langfuse (선택)

프롬프트/트레이스 관측. 자가호스팅 ECS. enableLangfuse 토글

Auth

SSO Token Service. API GW(IAM)+Lambda가 SSO ARN 검증→가상키 발급, DynamoDB 캐시, 팀 매핑

Observability

CloudWatch 대시보드(ALB 요청/5xx, Token Service, Langfuse 링크)

CDN

CloudFront(VPC Origin→내부 ALB). 유일한 공개 진입점·TLS 종단. Location 재작성 함수

cross-stack는 append-only *Exports 인터페이스 계약 + 런타임 SSM으로 결합(순환 의존성 0)

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

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

1
SSO 로그인 → 키 helper
aws sso login 후 boto3 SigV4 서명(리전은 Token URL에서 파싱)
신원 확보
2
API Gateway (IAM/SigV4)
서명된 caller ARN만 통과 — 미서명/무권한 거부
엣지 인가
3
Token Lambda — SSO ARN 검증
AWSReservedSSO_ 접두사 확인, 비-SSO는 403. 권한셋→팀(standard/economy) 매핑
신원 강제 · 티어링
4
가상키 발급·캐시 (DynamoDB)
LiteLLM /key/generate(master key는 Secrets Manager) → 키별 모델 allowlist·예산·MCP 그룹
키 거버넌스
5
CloudFront(TLS) → 내부 ALB → LiteLLM
ALB는 인터넷 비노출, CloudFront VPC Origin만 접근
네트워크 격리
6
Guardrail 통과 → Bedrock 호출
Claude는 시크릿탐지+Bedrock Guardrail 적용. Task Role SigV4(토큰 없음)
콘텐츠 안전
7
트레이스/사용량 기록
Langfuse(프롬프트·트레이스) + CloudWatch(인프라) + 키별 사용량/예산
감사·관측
거버넌스 · Governance

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

🪪 신원 (Identity)

IAM Identity Center(SSO)가 신뢰 기준. AWSReservedSSO_ ARN만 허용, 직접 IAM 롤 우회 차단(403)

🔏 인가 (AuthZ)

API Gateway AWS_IAM(SigV4). 권한셋에 execute-api:Invoke만 부여 — 최소 권한

🔑 키 라이프사이클

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

📊 티어링 · 예산

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

🛡️ 정책 (Policy)

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

🧾 감사 (Audit)

키별 사용량·예산, Langfuse 프롬프트/트레이스, CloudWatch 지표. cdk-nag 억제는 사유 명시

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

데이터는 어디에 머무는가

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

  • 대화/키/사용량 → Aurora Serverless v2 (격리 서브넷, 저장 암호화) — 배포 리전 내
  • 가상키 캐시 → DynamoDB (배포 리전, PITR)
  • 시크릿 → Secrets Manager (배포 리전)
  • 프롬프트/트레이스 → Langfuse → 동일 Aurora (리전 내)
  • 모델 추론 → Bedrock (선택 리전 inference profile)
  • CloudFront → CACHING_DISABLED — 본문을 엣지에 캐시하지 않음

🔒 격리 보장

  • 인터넷 미경유 — Bedrock·Secrets·SSM·ECR·Logs·AgentCore를 VPC 인터페이스 엔드포인트로 호출
  • ALB 비공개 — internal-only, CloudFront VPC Origin만 진입
  • DB 격리 — Aurora는 isolated 서브넷(egress 없음), SG로 LiteLLM/λ만 5432 허용
  • 리전 고정 — 메인 스택 단일 리전(CDN만 us-east-1 · CloudFront 요구사항)
  • 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커스텀 도메인litellm.certModeacm-dns(도메인+ACM+Route53) / 도메인리스(기본 cloudfront.net)
2관측성 깊이enableLangfuseLangfuse on / CloudWatch만
3모델·비용 티어Token Lambda 팀 매핑standard(전 모델) / economy(allowlist + 예산캡)
4제공 모델constants.MODELSClaude(bedrock/) + GPT(bedrock_mantle/) 조합
5리전(데이터 레지던시)CDK_DEFAULT_REGION메인 리전 고정 · CDN은 us-east-1
6용량·비용data.* · litellm.* · natGatewaysAurora ACU · Fargate 크기 · NAT 수
7부트스트랩bootstrapQualifier기본 / 커스텀(충돌 회피)

추가 토글: guardrail.enabled · observability.dashboardEnabled · agentcore.tavily*(MCP 웹검색) · auth.keyCacheTtlSeconds

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

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

1Discovery도메인·모델·티어·관측성·리전·MCP·SSO 질의
2Designdecision-tree 적용 · MCP로 모델 ID/리전 검증
3GenerateCDK·Lambda·LiteLLM·스크립트 생성
4Validatetypecheck · synth · cdk-nag 해소
5Deploybootstrap · cdk deploy
6OnboardingClaude Code/Codex 세팅 안내(항상 출력)

⛔ GATE 1 — 요구사항 확인

Discovery 답변과 그 결과 config/dev.json을 요약해 사용자 승인 후 진행

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

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

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

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

Skill이 생성하는 완성형 CDK 앱

project/ ├─ bin/app.ts # 8 스택 와이어링 ├─ config/dev.json # 선택값(런타임 검증) ├─ lib/ │ ├─ *-stack.ts # Network ~ CDN │ ├─ 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 게이트
  • SSO Token Service — API GW(IAM)+Lambda+DynamoDB
  • LiteLLM 컨테이너 — config.yaml · Mantle SigV4 오버레이
  • 개발자 온보딩 — 키 helper · Claude/Codex 설정 템플릿
  • 테스트·억제 — synth 단언 · 정당화된 cdk-nag suppression

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

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

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

🌍 리전 하드코딩 금지

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

🔁 UI 리다이렉트(도메인리스)

CloudFront Function이 Host로 Location 재작성 + PROXY_BASE_URL/NEXTAUTH_URL 공개도메인(2단계)

🧱 부트스트랩 충돌

잔존 리소스 시 커스텀 --qualifier로 비파괴 부트스트랩

⚖️ Mantle ↔ Guardrail

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

🔑 시크릿 외부화

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

🏗️ prod 전환 체크

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

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

설치 · 3개 도구 공통

한 SKILL.md, 세 곳에 설치

Claude Code

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

Kiro

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

Amazon Quick

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

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

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

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

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

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

  • 8개 스택 전부 CREATE_COMPLETE
  • ECS LiteLLM·Langfuse 1/1 running
  • CloudFront → 내부 ALB → LiteLLM /health 200
  • SSO 강제 비-SSO 호출 403 (설계대로)
  • SSO 사용자 발급 → 가상키 → Claude 정상 응답
  • UI LiteLLM·Langfuse 로그인 동작(도메인리스)
8/8

스택 배포

3계층

Guardrail

100%

토큰리스 SigV4

3툴

md5 동일 SKILL

실 배포에서 발견한 이슈(리전·UI 리다이렉트·키 레이스)는 모두 Skill에 역반영

시작하기

이렇게 말하면 됩니다

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

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

DiscoveryDesignGenerate ValidateDeployOnboarding
⬇ 스킬 다운로드 (.zip)

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

llm-gateway-governance-skill · Claude Code · Kiro · Amazon Quick