View a markdown version of this page

Claude 앱 게이트웨이를 사용하여 Claude Code 설정 - Amazon CloudWatch
주요 기능사전 조건게이트웨이 배포게이트웨이에 개발자 연결원격 분석을 Amazon CloudWatch로 라우팅가용성 및 제한 사항다음 단계

Claude 앱 게이트웨이를 사용하여 Claude Code 설정

Claude 앱 게이트웨이는 개발자의 Claude Code 클라이언트와 모델 제공업체 사이에 있는 자체 호스팅 서비스입니다. 개발자는 API 키나 클라우드 자격 증명을 보유하는 대신 회사 ID 제공업체(idP)로 로그인합니다. 게이트웨이는 업스트림 자격 증명을 보유하고, IdP 그룹의 모델 액세스 및 관리형 설정을 적용하고, Amazon CloudWatch를 포함한 관찰성 스택에 사용량 원격 분석을 릴레이합니다.

게이트웨이는 claude 바이너리에 포함됩니다. 구성 파일과 함께 gateway 하위 명령을 전달하면 Claude Code를 실행하는 것과 동일한 실행 파일이 게이트웨이를 실행합니다.

주요 기능

Claude 앱 게이트웨이는 여러 차원에서 중앙 집중식 제어를 제공합니다.

  • 자격 증명 - 업스트림 API 키는 인프라에만 있습니다. 개발자는 수명이 짧은 토큰을 사용하여 SSO를 통해 인증합니다.

  • 액세스 제어 - IdP 그룹은 모델 허용 목록 및 관리형 설정 정책에 매핑됩니다.

  • 설정 전송 - 게이트웨이는 로그인한 클라이언트에 관리형 설정을 전송합니다.

  • 원격 분석 - OTLP 지표(토큰 수, 모델, 사용자 ID, 지연 시간)를 수집기로 라우팅합니다. CloudWatch, Datadog, Splunk 및 ClickHouse를 비롯한 여러 대상으로 팬아웃할 수 있습니다.

  • 업스트림 라우팅 - 클라이언트는 Anthropic Messages API를 사용합니다. 게이트웨이는 장애 조치를 통해 각 업스트림에 대해 변환합니다. 지원되는 업스트림에는 Amazon Bedrock, Claude Platform on AWS, Google Cloud의 에이전트 플랫폼, Microsoft Foundry 및 Anthropic API가 포함됩니다.

사전 조건

게이트웨이를 배포하기 전에 다음 요구 사항이 충족되는지 확인합니다.

요구 사항 세부 정보
Claude Code 버전 v2.1.195 이상
ID 공급자 Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex 등의 OpenID Connect(OIDC) 제공업체
데이터베이스 PostgreSQL 14 이상
모델 업스트림 Amazon Bedrock 자격 증명, Claude Platform on AWS, Google Cloud, Microsoft Foundry 또는 Anthropic API 키
TLS HTTPS 인증서 또는 TLS 종료 수신
Network 프라이빗 네트워크 주소(RFC 1918, 링크-로컬, CGNAT, IPv6 ULA 또는 루프백)
런타임 프로덕션용 Linux(로컬 개발 전용 macOS)

게이트웨이 배포

다음 절차는 빠른 시작 단계를 요약합니다. 자세한 지침은 Claude 앱 게이트웨이 설명서를 참조하세요.

Claude 앱 게이트웨이를 배포하려면

  1. IdP에 OAuth 클라이언트를 등록합니다. 리디렉션 URI를 https://claude-gateway.your-domain/oauth/callback으로 설정합니다.

  2. PostgreSQL 데이터베이스(PostgreSQL 14 이상 인스턴스)를 프로비저닝합니다. 게이트웨이는 부팅 시 스키마 마이그레이션을 실행합니다.

  3. gateway.yaml 구성 파일을 작성합니다. 다음 예제에서는 Amazon Bedrock을 업스트림으로 사용하는 최소 구성을 보여줍니다.

    listen:
  host: 0.0.0.0
  port: 8080
  public_url: https://claude-gateway.internal.example.com

oidc:
  issuer: https://login.example.com
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains: [example.com]
  userinfo_fallback: true

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}
  ttl_hours: 1

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}

auto_include_builtin_models: true

  4. 게이트웨이를 실행합니다. Docker Compose를 사용하거나 바이너리를 직접 실행할 수 있습니다.

    claude gateway --config gateway.yaml

  5. 인증 표면을 확인합니다. 게이트웨이 URL에서 검색 문서를 가져오고, 디바이스 권한 부여를 요청하고, 브라우저 로그인을 테스트합니다.

  6. 개발자로 로그인하여 엔드 투 엔드 연결을 확인합니다.

게이트웨이에 개발자 연결

개발자 시스템이 게이트웨이를 가리키도록 하려면 모바일 디바이스 관리(MDM) 또는 구성 관리 도구를 통해 다음 관리형 설정 키를 배포합니다.

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"
}

설정을 배포한 후 각 개발자는 다음 단계를 완료합니다.

게이트웨이를 통해 로그인하려면

  1. Claude Code에서 /login 명령을 실행합니다.

  2. 클라우드 게이트웨이 화면에서 Enter 키를 누릅니다.

  3. 회사 IdP로 브라우저 로그인을 완료합니다.

로그인 후 Claude Code는 게이트웨이를 통해 추론을 라우팅하고 게이트웨이는 원격 분석을 구성된 대상으로 내보냅니다.

원격 분석을 Amazon CloudWatch로 라우팅

게이트웨이는 ID 스탬프 내보내기를 사용하여 여러 수집기로의 OTLP/HTTP 팬아웃을 지원합니다. gateway.yaml 파일에서 원격 분석 대상을 구성합니다. 각 대상은 지표, 로그 또는 트레이스를 수신할 수 있습니다.

CloudWatch를 원격 분석 대상으로 구성하면 게이트웨이는 각 내보내기에 IdP의 개발자 ID를 스탬핑합니다. 지표는 사용자, 팀 및 조직 속성과 함께 도착하므로 동일한 Coding Agent Insights 대시보드가 채워집니다.

전체 원격 분석 구성 옵션은 구성 참조를 확인하세요.

가용성 및 제한 사항

다음 표에는 게이트웨이가 지원하는 사항과 현재 제한 사항이 요약되어 있습니다.

항목 Status
지원되는 업스트림 Amazon Bedrock, Claude Platform on AWS, Google Cloud의 에이전트 플랫폼, Microsoft Foundry, Anthropic API
지원되는 IdP Okta, Microsoft Entra ID, Google Workspace, Keycloak, Dex 및 기타 OIDC 준수 제공업체
원격 분석 프로토콜 여러 대상으로 팬아웃되는 OTLP/HTTP
런타임 프로덕션 배포용 Linux. macOS는 로컬 개발에서만 지원됩니다.
최소 Claude Code 버전 v2.1.195

다음 단계

자세한 배포 지침, 구성 옵션 및 운영 지침은 다음 리소스를 참조하세요.

  • Claude 앱 게이트웨이 설명서 - Docker Compose 템플릿 및 IdP 등록 안내서를 포함한 전체 설정 가이드입니다.

  • 구성 참조 - 원격 분석 대상, 업스트림 라우팅 및 액세스 정책을 포함한 모든 gateway.yaml 옵션에 대한 전체 참조입니다.

  • 배포 가이드 - 프로덕션 배포 패턴, 규모 조정 및 운영 모범 사례입니다.

게이트웨이가 CloudWatch로 지표를 전송한 후에 대시보드 보기에 설명된 대로 대시보드를 봅니다.