AI 코딩 도구를 사용하기 시작하는 거의 모든 회사에서 발생하는 현상이 있습니다. 한 개발자가 Anthropic API 키를 확보하여 동료 두 명에게 알려주면, 일주일 이내에 팀의 절반이 .env 파일, 셸 프로필(shell profiles), CI 작업(CI jobs)에 자신만의 키를 저장하게 됩니다. 누군가 퇴사합니다. 그들의 키는 여전히 어딘가에서 활성화되어 있습니다. 당신은 그 키가 무엇을 호출하고 있는지, 비용을 얼마나 쓰고 있는지 전혀 알 수 없습니다.

더 나은 모델이 있습니다. 이 포스트에서는 전체 엔지니어링 팀이 단 하나의 API 키나 AWS 자격 증명(credential)도 개발자 노트북에 남기지 않고 Claude Code를 사용할 수 있게 해주는 오픈 소스(open-source) AWS 설정을 살펴봅니다. 또한 몇 가지 아키텍처(architectural) 트릭을 통해 일반적인 기업용 솔루션의 마찰 없이 어떻게 이를 구현할 수 있는지 설명합니다.

게이트웨이가 실제로 하는 일

Claude Apps Gateway는 자신의 AWS 계정에서 실행하는 셀프 호스팅(self-hosted) 프록시(proxy)입니다. 아키텍처는 의도적으로 단순합니다:

┌ your AWS account (private VPC) ──────────────────────────────┐
│  internal IPv4 ALB → ECS Fargate (claude gateway)            │
│      ├─ OIDC → your IdP (Cognito / Okta / Entra / …)         │
...

개발자는 claude /login을 실행하고 브라우저에서 기업용 SSO(Single Sign-On)를 완료하며(MFA, 조건부 액세스(conditional access) 등 IdP가 강제하는 모든 사항 포함), 수명이 짧은 JWT를 발급받습니다. 이것이 그들의 자격 증명(credential)이 됩니다. 게이트웨이는 Bedrock IAM 역할을 보유하며, 이는 절대 AWS를 벗어나지 않습니다. 오프보딩(Offboarding)은 IdP에서 해당 사용자를 제거하는 것뿐입니다.

이 모든 것을 설정하는 리포지토리(repo)는 github.com에 있으며, 자신의 리포지토리에 복사하여 그대로 배포할 수 있는 독립형 CloudFormation 스택(stack)입니다.

한 번의 명령으로 실행하기

이 리포지토리는 일반적인 시작 지점을 커버하는 5개의 .env 프로필을 제공합니다:

현재 상태…	프로필
아직 아무것도 없음 (greenfield)	managed-newcognito-collector-vpn.env
...

하나를 복사하고 약 5개의 값(도메인, Route53 zone ID, IdP 세부 정보)을 채운 뒤 실행하세요:

cp config/managed-newcognito-collector-vpn.env config/my.env
$EDITOR config/my.env      # domain, zone, region — 그게 거의 전부입니다

...

오케스트레이터(Orchestrator)는 모든 것을 체인(chain)으로 연결합니다: IdP 스택 → 게이트웨이(gateway) 스택 → 선택적 ADOT 컬렉터(collector) → 선택적 Client VPN. 마지막에는 게이트웨이 URL, CloudWatch 대시보드 링크, 그리고 VPN이 포함된 경우 .ovpn 경로가 포함된 요약 정보를 출력합니다.

이미 자체적인 IdP, OTLP 컬렉터, 그리고 프라이빗 네트워크 경로를 보유하고 있다면, deploy-all.sh를 완전히 건너뛰고 기존 엔드포인트를 사용하여 deploy.sh를 직접 호출하세요. 이 경우 아무것도 번들링되지 않은 상태로 배포됩니다.

빌려올 만한 가치가 있는 세 가지 아키텍처 트릭

1. 공개 인증서 + 프라이빗 주소

ALB는 내부용(internal)이며 IPv4 전용입니다. 이는 선택 사항이 아닙니다. Claude Code의 /login 흐름은 공개 IP 주소로 해석되는 게이트웨이를 명시적으로 거부하므로, 격리(isolation)는 정책이 아닌 클라이언트에 의해 강제됩니다.

하지만 인증서는 브라우저에서 신뢰할 수 있어야 하며, 모든 노트북에 자체 서명된 CA(Certificate Authority)를 배포하지 않고 이를 달성하는 것은 매우 고통스러운 일입니다. 해결책은 다음과 같습니다: 귀하의 도메인에 대해 DNS 검증을 거친 공개 ACM 인증서를 발급한 다음, 공개 A 레코드(A-record)가 내부 ALB를 가리키도록 설정하는 것입니다.

도메인은 프라이빗 네트워크를 통해서만 도달 가능한 프라이빗 IP(10.20.x.x)로 해석됩니다. 하지만 인증서는 공개 DNS 이름을 통해 검증되었으므로 브라우저가 이를 신뢰합니다. NODE_EXTRA_CA_CERTS 설정도, 키체인(keychain) 가져오기도, 지문(fingerprint) 확인 프롬프트도 필요 없습니다.

2. 설정은 SSM이 아닌 태스크 정의(task definition)에 존재

렌더링된 gateway.yaml 설정은 ECS 태스크 정의(task-definition)의 환경 변수로 전달됩니다. 이는 모델 허용 목록(allowlist), 텔레메트리(telemetry) 엔드포인트, RBAC 정책 등 어떠한 설정 변경이라도 새로운 태스크 정의 리비전(revision)을 강제하며, ECS는 이를 반영하기 위해 실행 중인 태스크를 자동으로 순환(cycle)시킵니다.

우리는 런타임(runtime)에 SSM에서 설정을 가져오는 이전 버전을 시도했습니다. 하지만 미묘한 방식으로 문제가 발생했습니다. SSM에서 텔레메트리(telemetry) 엔드포인트를 업데이트하더라도, 실행 중인 태스크는 수동으로 순환(recycle)시키기 전까지 계속해서 이전 엔드포인트를 사용했습니다. 태스크 정의(taskdef) 내에 설정을 포함하는 방식(Config-in-taskdef)은 배포 프로세스를 신뢰할 수 있는 단일 원천(source of truth)으로 만듭니다.

제약 사항은 4096바이트의 ECS 환경 변수(env var) 제한입니다. 현재 렌더링된 크기는 약 3000바이트입니다. deploy.sh는 렌더링된 설정이 제한을 초과할 경우 바이트 수를 표시하며 즉시 실패(fail fast)합니다.

3. Docker에서의 GPG 검증된 바이너리 다운로드

Dockerfile은 2단계 빌드(two-stage build)를 사용합니다. 1단계(Stage 1)에서는 Anthropic의 릴리스 서명 키(지문은 하드코딩됨)를 가져오고, 서명된 매니페스트(manifest)를 다운로드하며, 분리된 서명(detached signature)을 검증합니다. 그 후 claude Linux 바이너리를 다운로드하고 매니페스트와 비교하여 SHA256 체크를 수행합니다. 검증된 바이너리만이 런타임 단계(runtime stage)로 복사됩니다.

# stage 1: verify
RUN gpg --import anthropic-release-key.asc \
 && gpg --verify manifest.json.sig manifest.json \
...

런타임 이미지는 ca-certificates만 추가된 debian:stable-slim입니다. 검증 도구는 프로덕션(production) 환경으로 배포되지 않습니다.

새로운 시스템 없는 RBAC

그룹 기반 액세스 제어(access control)는 두 개의 환경 변수(env var)만으로 가능합니다:

export DENY_TOOL_GROUP=contractors
export DENY_TOOLS="mcp__bash,mcp__computer"

deploy.sh는 이를 게이트웨이 설정의 managed.policies 블록으로 렌더링합니다. 이는 지정된 IdP 그룹에 대해 해당 도구들을 거부(deny)하는 선입선출(first-match) 방식의 정책 리스트이며, 그 외의 모든 사용자는 제한 없이 허용하는 catch-all 정책을 포함합니다:

managed:
  policies:
    - name: contractors-deny-shell
...

모델 허용 목록(allowlists)도 동일한 방식으로 작동합니다. 엔지니어링 팀은 Opus를 사용하고, 계약업체는 Haiku를 사용합니다. 정책 변경은 재배포(redeploy) 시 적용되며, 사용자의 새로운 그룹 멤버십은 다음 claude /login 시점에 적용됩니다.

관찰 가능성(Observability): 메트릭(metrics) vs 로그 인사이트(Logs Insights)

번들로 포함된 ADOT collector는 OTLP 이벤트를 CloudWatch로 내보냅니다. user.email과 user.groups만이 token.usage 및 cost.usage 이벤트의 CloudWatch EMF 메트릭 **차원 (dimensions)**으로 승격됩니다. 각각의 고유한 차원 값은 새로운 커스텀 메트릭을 생성하며, CloudWatch는 메트릭당 비용을 부과합니다. 따라서 차원의 카디널리티 (cardinality)를 낮게 유지해야 합니다.

사용자별 지출 내역 분석, 역할별 분석과 같은 고카디널리티 (high-cardinality) 슬라이싱은 /aws/claude-gateway/events를 대상으로 CloudWatch Logs Insights에서 수행됩니다. Logs Insights는 스캔된 GB당 비용이 청구되는데, 이는 임시 쿼리 (ad-hoc queries)를 수행할 때 수십 배 더 저렴합니다.

CloudWatch Metrics  → "팀 A의 일일 지출액은 얼마인가?" (대시보드, 알람)
Logs Insights       → "화요일에 지출이 급증한 사용자는 누구인가?" (임시 쿼리)

FORWARD_LOGS=true를 설정하여 로그 전달을 활성화하세요. 기본값은 꺼져 있으며, 메트릭만 사용하는 것이 기본 설정입니다.

우리가 겪은 문제점들 (Gotchas)

VPN 터널 MTU. 만약 /login에서 아무런 반응 없이 멈춘다면, VPN MTU를 의심해 보세요. MTU가 1500인 경우, TLS 핸드셰이크 (handshake) 패킷이 파편화되어 드롭될 수 있습니다. 해결 방법: sudo ifconfig utunN mtu 1300. 이는 VPN에 재연결할 때마다 초기화되므로, 연결 스크립트에 포함시키세요.

호스트 이름 변경 시 오래된 클라이언트 상태. 자체 서명 인증서에서 관리형 ACM 인증서로 전환할 때 (호스트 이름 변경), ~/.claude/remote-settings.json과 macOS 키체인 항목인 Claude Code-credentials 모두 이전 호스트를 고정(pin)합니다. 재연결하기 전에 둘 다 삭제하거나 claude /logout을 실행하세요.

ACM 검증이 약 90분간 중단되는 현상. PUBLIC_HOSTED_ZONE_ID가 프라이빗 존(private zone)이거나, DOMAIN_NAME이 지정한 존 아래에 있지 않은 경우 발생합니다. 현재 deploy.sh는 이 두 가지를 사전에 점검하여 즉시 실패하도록 처리되어 있습니다. 하지만 이전 버전을 사용 중이라면, 멈춰 있는 ACM 인증서를 삭제하고 다시 배포하세요.

Postgres DSN 내의 RDS 생성 비밀번호. RDS는 #, %, & 및 기타 URL 구조 문자를 포함하는 비밀번호를 생성할 수 있습니다. entrypoint.sh는 런타임에 postgres:// DSN을 조립하며, 이미지 내에 Python이나 Perl 없이 순수 bash를 사용하여 비밀번호를 퍼센트 인코딩 (percent-encode) 합니다.

비용 분석

게이트웨이 라이선스 비용이 없습니다. AWS 인프라 비용과 일반적인 Bedrock 토큰당 과금 방식(per-token pricing)을 지불하면 됩니다. 이는 Bedrock을 직접 호출할 때와 동일합니다.

리소스	대략적인 비용
2× ECS Fargate 태스크 (AZ 간 고가용성(HA) 확보)	월 약 $9
...

팀 규모에 관계없이 고정 인프라 비용은 대략 월 $40입니다. 필요하지 않을 때는 ECS를 0으로 스케일링하거나 스택을 제거할 수 있습니다.

직접 시도해보기

이 스택은 MIT 라이선스를 따르며, 독립적(self-contained)이고 사용자의 자체 계정에 배포됩니다. SaaS 의존성도, 라이선스 서버도, 외부로 데이터를 전송(phoning home)하는 기능도 없습니다.

소스 코드는 위의 링크에 있습니다. 직접 사용해 보다가 '주의 사항(gotchas)' 목록에 없는 문제에 부딪힌다면 이슈(issue)를 생성해 주세요. docs/GUIDE.md에 있는 트러블슈팅 가이드는 이를 실행하는 팀이 늘어남에 따라 계속 업데이트됩니다.