Claude apps gateway 배포와 운영
공식 기준: https://code.claude.com/docs/en/claude-apps-gateway-deploy
기준일: 2026-07-26 · CLI 기준 2.1.220
개요
gateway는 단일 Linux 바이너리이며 복제본은 stateless, Postgres가 공유 조율 계층입니다. 조직 네트워크 안에서 upstream 자격증명을 들고 inference 단일 egress 역할을 합니다.
핵심 개념
IdP 요구
- OIDC well-known (
https프로덕션; loopback은CLAUDE_GATEWAY_ALLOW_LOOPBACK=1) - authorization-code (+ 기본 PKCE)
- email, 선택 groups
- redirect:
https://<gateway>/oauth/callback
Refresh token(offline_access)이 있으면 silent renewal과 빠른 deprovision(다음 refresh 실패)이 가능합니다. 없으면 TTL을 늘려 재로그인을 줄이되 deprovision 지연 tradeoff가 있습니다.
배포 결정
- 비용: gateway 별도 라이선스 없음; inference·compute·텔레메트리 비용
- Bypass: gateway가 유일한 경로임을 강제하지 않음 — egress 정책으로 직접 provider 호출 차단.
api.anthropic.com차단 시 WebFetch preflight 영향 → managedskipWebFetchPreflight: true검토 - 다중 gateway: 호스트명별 trust·자격증명 분리; 다중 OIDC issuer는 인스턴스 분리
- Serverless: Cloud Run OK (
min-instances: 1); Lambda/Functions 비적합
상세
컨테이너 이미지
- 핀된 릴리스에서 Linux 바이너리 다운로드
- GPG-signed
manifest.json검증 - glibc 기반 이미지 권장 (musl은 전용 빌드)
CLAUDE_CONFIG_DIR쓰기 가능 경로- CMD:
claude gateway --config /etc/claude/gateway.yaml
Kubernetes
- ConfigMap/Secret 마운트
- Ingress TLS,
public_url= Ingress 호스트 - readiness
GET /readyz, livenessGET /healthz - 워크로드 아이덴티티(IRSA/GKE WI/AKS) 선호,
auth: {}또는 Foundryuse_azure_ad: true
Cloud Run
- port 8080/
PORT - production
public_url은 보통 internal LB (public*.run.app는/login거절; Private Service Connect 등 private 해석 예외) - secret volume,
min-instances: 1
개발자 기기 URL 배포
managed settings / MDM으로 gateway URL 푸시.
운영
| 영역 | 요지 |
|---|---|
| Logs | CLAUDE_GATEWAY_LOG_LEVEL; 감사는 별도 |
| Health | /healthz, /readyz |
| Outage | upstream 장애 시 failover·에러 표면 |
| JWT secret rotation | 롤링 키 전략 |
| Postgres | 백업·연결 수·private IP |
| Upgrades | 바이너리 핀·호환 설정 확인 |
보안
- data flow: 클라이언트→gateway→upstream; IdP; OTLP
- threat model: 탈취된 토큰, 설정 push, brute-force user-code
- compliance: residency·감사 보관은 조직 책임 범위 문서화
문제 해결
OIDC discovery 실패, redirect mismatch, groups claim 부재, trusted_proxies 미설정 rate limit 붕괴, public URL login 거절 등을 순서대로 점검합니다.
체크리스트
- IdP client·claims 검증
- 이미지 서명 검증·버전 핀
- private 노출 + trusted_proxies
- readiness/liveness·로그 파이프라인
- egress bypass 정책 검토