AWS GenAI Lab · LLM Gateway Governance · 사전 준비

이 Skill로 LLM Gateway를 구축하기 전에

Kiro · Claude Code · Codex와 대화하며 사내 개발자용 LLM 거버넌스 게이트웨이를 AWS에 배포합니다.

아래 6가지를 Phase 1 Discovery 시작 전에 모두 확인하면, 배포 중간(cdk deploy)에서의 실패를 예방할 수 있습니다.

Phase 1 전에 모두 ✓ — 하나라도 빠지면 특정 단계에서 블로커
이건 Agent Skill이지 독립 실행 CLI가 아닙니다 — SKILL.md를 로드해 다단계 워크플로우를 구동하는 AI 코딩 도구 안에서만 동작합니다. 아래 3개 중 하나가 설치돼 있어야 합니다. (Docker/Node/CDK/AWS CLI 등 나머지 준비물은 모두 이 도구 안에서 검증됩니다.)

1 Skill을 실행할 AI 도구 (하나 선택) 필수

도구설치Skill 설치 경로
Kirohttps://kiro.dev~/.kiro/skills/llm-gateway-governance/
Claude Codenpm install -g @anthropic-ai/claude-code · docs~/.claude/skills/llm-gateway-governance/
Codexnpm install -g @openai/codex · developers.openai.com/codex~/.agents/skills/llm-gateway-governance/

설치 명령(ln -sf / cp -r)은 스킬 README.md → Install 섹션 참고. 다운로드: llm-gateway-governance-skill.zip

Docker는 권장 사항입니다 — 필수는 아닙니다. 로컬에 Docker 데몬이 켜져 있으면 cdk deploy(Phase 5)가 LiteLLM 프록시 이미지를 CDK fromAsset으로 가장 빠르게 빌드하므로 권장합니다. 이 경로를 쓸 때는 실패가 synth 성공 이후에 늦게 발생하니 배포 전에 데몬을 미리 켜 두세요. Docker가 없거나 설치할 수 없는 머신이라면(예: WSL2/Hyper-V 설치가 금지된 관리형 Windows) litellm.imageBuild.mode='codebuild'로 전환해 이미지를 CodeBuild(네이티브 ARM)에서 빌드하면 됩니다 — 배포는 그대로 완주됩니다(스킬 문서 cdk-stacks.md §4-1, 3단계 배포).

2 로컬 도구 필수

도구최소 버전왜 필요한가 · 확인
Docker (데몬 실행) 권장최신LiteLLM 이미지 fromAsset 로컬 빌드(가장 빠름) · docker info
없으면 litellm.imageBuild.mode='codebuild'로 대체 가능
Node.js18.x / 20.x LTSCDK 앱 + npm/npx · node -v
AWS CDK CLIv2synth/deploy/bootstrap · cdk --version
AWS CLIv2SSO 로그인·CLI 검증 · aws --version
jq 선택anyoutputs.json 파싱 · jq --version

M macOS 설치 macOS

brew install --cask docker      # 설치 후 1회 실행해 데몬 기동
brew install node@20            # 또는 nvm install 20 && nvm use 20
npm install -g aws-cdk
brew install awscli jq

docker info 가 "Cannot connect to the Docker daemon" 이면 Docker Desktop을 실행하고 재시도.

L Linux 설치 (Ubuntu/Debian) Linux

# Docker Engine (배포판 docker.io는 구버전 → 공식 스크립트 권장)
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
# Node 20 (nvm 권장)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc && nvm install 20
npm install -g aws-cdk
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o awscliv2.zip
unzip awscliv2.zip && sudo ./aws/install       # ARM: -linux-aarch64.zip
sudo apt-get update && sudo apt-get install -y jq

W Windows 설치 (WSL2 권장) Windows

가장 매끄러운 경로는 WSL2(Ubuntu) 안에서 위 Linux 절차를 그대로 실행하는 것입니다. 네이티브 PowerShell도 가능합니다.

wsl --install                   # 관리자 PowerShell, 재부팅 후 위 Linux 절차
# Docker Desktop: Settings → "Use the WSL 2 based engine" + Resources → WSL Integration
winget install OpenJS.NodeJS.LTS
npm install -g aws-cdk           # cdk deploy를 실행할 셸(WSL 또는 PowerShell)에서
winget install Amazon.AWSCLI
winget install jqlang.jq
⚠️ WSL과 PowerShell을 섞지 마세요. npm install -g는 실행한 셸에만 cdk를 노출합니다 — cdk deploy를 실행할 한쪽 셸에 설치. Docker Desktop만 WSL 통합으로 양쪽 공유됩니다.
WSL2/Hyper-V를 설치할 수 없다면? Docker Desktop은 둘 중 하나가 필요하고, 둘 다 관리자 설치 + 재부팅이 필요합니다 — 관리형 사내 노트북에서 불가한 경우(실제 보고 사례) Docker와 싸우지 말고 CodeBuild 이미지 빌드 경로(litellm.imageBuild.mode='codebuild')로 전환하세요. 이 표의 나머지 도구는 모두 PowerShell에서 네이티브로 동작하며, 이미지는 CodeBuild(네이티브 ARM)에서 빌드됩니다.

검증 한 번에 확인 (전 OS 공통)

설치 후 실행 — Docker 외 항목이 실패하면 Phase 1 전에 해결해야 합니다.

docker info    >/dev/null 2>&1 && echo "✅ Docker 데몬"   || echo "⚠️  Docker(권장) — codebuild 모드로 대체 가능"
node -v        >/dev/null 2>&1 && echo "✅ Node: $(node -v)" || echo "❌ Node.js"
cdk --version  >/dev/null 2>&1 && echo "✅ CDK: $(cdk --version)" || echo "❌ CDK"
aws --version  >/dev/null 2>&1 && echo "✅ AWS CLI" || echo "❌ AWS CLI"
jq --version   >/dev/null 2>&1 && echo "✅ jq" || echo "⚠️  jq(선택)"
게이트웨이 플랫폼 스택은 한 계정에 배포됩니다. AgentCore Web Search와 Mantle(GPT-5.6 Sol/Terra/Luna · 5.5 · 5.4)은 게이트웨이 리전과 무관하게 us-east-1 고정이라, 게이트웨이 리전 + us-east-1 두 곳 모두 cdk bootstrap이 가능해야 합니다. (CloudFront는 제거됨 — ALB가 엣지, ACM은 리전 인증서)

3 AWS 계정 접근 필수

요구사항세부
대상 계정게이트웨이용 계정 1개. sandbox/dev 계정의 Administrator가 가장 간단(공유/prod면 배포 롤을 스코프)
배포 IAM 권한VPC/네트워킹 · Aurora Serverless v2 · ECS Fargate + ALB · Secrets Manager · IAM 롤 · API Gateway · Lambda · ACM(리전) (+ 도메인 사용 시 Route53) · BedrockAgentCore::Gateway · EC2 VPC peering · Route53 PHZ · (SSO 프로비저닝 시 sso-admin/identitystore)
CDK bootstrap게이트웨이 리전 + us-east-1 양쪽. 다른 팀이 다른 qualifier로 bootstrap했다면 커스텀 --qualifier 준비
Bedrock 모델 액세스Claude 모델 → 게이트웨이 리전, GPT-5.6 Sol/Terra/Luna · 5.5 · 5.4(Mantle) → us-east-1 에서 Model access 활성화
AWS MarketplaceMantle은 Marketplace 오퍼링 — 계정이 구독 가능해야 함(첫 호출 자동 구독). 구매 제한 계정은 부적합
서비스 쿼터첫 배포엔 기본 쿼터로 충분. 기존 워크로드가 많으면 VPC/EIP 쿼터 점검
계정 확인 
aws sts get-caller-identity     # 의도한 대상 계정으로 resolve 되는지 확인
AWS IAM Identity Center를 어떻게 쓸 수 있는지 "결과만" 확인해 오면 됩니다. 권한셋·Cognito 등 상세 설정은 스킬이 배포 중에 알아서 처리·안내하므로, 여기서는 어느 쪽인지만 알면 충분합니다.

4 IAM Identity Center 가능 여부 확인 필수

다음 둘 중 어느 쪽인지만 확인하세요 — 잘 모르면 조직/계정 관리자에게 물어봐도 됩니다.

확인 결과이 스킬이 자동으로 쓰는 방식
Organization(조직) IAM Identity Center를 쓸 수 있음조직 SSO 로그인 경로로 배포
Linked(계정) 인스턴스뿐 · 조직 IdC 못 씀 · IdC 없음Cognito 로그인 경로로 배포
둘 중 어느 쪽인지만 알고 오면 됩니다 — 나머지(권한셋 생성, Cognito User Pool 등)는 스킬이 배포 단계에서 처리·안내합니다.
게이트웨이를 어떤 주소로 열지 정하는데, 사용할 수 있는 도메인이 있는지 없는지만 확인해 오면 됩니다. 세부 방식(인증서 발급 · 내부 터널 등)은 스킬이 배포 중에 처리·안내합니다.

5 사용 가능한 도메인 유무 확인 필수

확인 결과이 스킬이 자동으로 쓰는 방식
쓸 수 있는 도메인 있음 (Route53 호스티드존 또는 인증서)그 도메인으로 HTTPS 공개 (권장)
도메인 없음도메인 없이도 배포 — 자체 인증서 또는 내부 접속(터널)

쓸 수 있는 도메인(또는 서브도메인)이 있는지만 확인하면 됩니다. 없어도 배포는 가능합니다.

본인 노트에 복사해 배포 직전 최종 점검하세요. 하나라도 ❌면 Phase 1 Discovery 진행 금지.

체크 배포 전 사전요건

  • ▢ Kiro / Claude Code / Codex 중 하나 설치 + 이 스킬 링크
  • ▢ docker info 성공(데몬 실행) — 권장, 없으면 imageBuild.mode='codebuild'로 대체
  • ▢ node -v → 18/20 · cdk --version → v2 · aws --version → v2
  • ▢ aws sts get-caller-identity 가 의도한 대상 계정으로 resolve
  • ▢ 배포 자격증명이 VPC/ECS/RDS/Lambda/APIGW/ALB/ACM/IAM 생성 가능
  • ▢ Bedrock 모델 액세스: Claude(게이트웨이 리전) + GPT-5.6 Sol/Terra/Luna · 5.5 · 5.4(us-east-1) 활성화
  • ▢ 계정이 AWS Marketplace 구독 가능(Mantle 첫 호출 자동 구독)
  • ▢ IAM Identity Center: 조직(Organization)을 쓸 수 있는지 / Linked(계정) 인스턴스인지 결과만 확인
  • ▢ 사용 가능한 도메인 유무 확인 (있으면 HTTPS 공개, 없으면 도메인 없이 배포)
  • ▢ cdk bootstrap — 게이트웨이 리전 + us-east-1 양쪽 가능

근거: 스킬 shared/reference/prerequisites.md · constraints.md · sso-setup.md · account-instance-setup.md