Claude Code Workshop - Chapter 3 Admin Setup

AWS 최우형님의 GitHub Claude Code Deep Dive Workshop 을 보면서 스스로 공부한 내용을 작성했습니다.

포스팅 모든 자료는 해당 워크숍 커리큘럼에서 학습했습니다.

* 자료 출처

GitHub - whchoi98/claude-code-workshop: claude-code-workshop

 

1. Admin Setup

1.1. 사전 내용

학습 내용
- 조직 규모의 설치와 인증 체계 설계
- Managed Settings 로 정책 강제
- OTel 및 대시보드를 통한 사용 관측
- 컴플라이언스 요구에 응답

 

• 배포 설계
  - 설치 채널과 미러, 버전 통제를 통한 대량 배포 설계
• 인증 체계
  - 공급자 선택
  - SSO, 자격증명 회전 체계 구축
• 정책 강제
  - Managed Settings 4채널(배포 경로)과 강제 키로 거버넌스 확립
• 관측과 대응
  - OTel, 비용 귀속, 감사 로그로 운영 가시화

 

조직 플랫폼 구축할 때 고려할 점

• Scale - 500명에게 어떻게 배포하고 갱신??
• Security - 키를 나눠주지 않고 인증하려면??
• Enforce, Governance - 금지 명령과 도메인 강제 방법
• Audit - 누가 얼마나 쓰는지, 감사는 어떻게 할건지?

 

1.2. Scale - 배포 전략

배포 채널

- 챕터 1에서 진행했던 클로드 설치방법

1. Native 스크립트
   - claude.ai/install.sh, 단일 바이너리, 자동 갱신
   - 표준 권장
2. OS 패키지 저장소
   - apt, dnf, apk 저장소
   - GPG 서명
3. 패키지 매니저
   - Homebrew cask
   - WinGet
4. 컨테이너
   - 표준 이미지
   - devcontainer
5. npm (레거시)
   - Node 의존

 

오프라인, 에어갭 환경에서의 클로드 사용

• 오프라인 환경(Offline)
  - 임시로 인터넷 연결이 끊겨있는 환경
  - 재연결 가능성 존재
• 에어갭 환경(Air-Gap)
  - 네트워크 연결이 완전히 차단된 환경
  - 물리적/논리적으로 완전히 격리되어 네트워크 연결이 안되는 상태

1. 설치(Install)
   - 사내 미러(Mirror) - Artifactory, Nexus
   - 이미지 레지스트리를 통한 완전 내재화
2. 추론 경로(Inference)
   - Bedrock + PrivateLink 를 통한 프라이빗 연결
3. 정책 배포(Policy)
   - 파일 기반 Managed Settings 를 형상 관리로 배포
4. 한계 인지(Limit)
   - 웹 검색 등 외부 의존 기능은 도메인 정책으로 차단 명시

 

사용량, 용량 예측

• 도입 전 산정 기준
  • 좌석 산정 - 인원
    - 활성 개발자 기준. 파일럿 실측으로 배수 보정
  • 토큰 추정
    - 1인 1일 세션 수와 평균 규모를 파일럿에서 실측
  • 모델 배분
    - Sonnet 중심, Opus 비중이 비용의 지배 변수
  • 피크 대비
    - 클라우드 경로(Bedrock)는 Region 사용량과 Throttle 한도 사전 확인

 

배포 전 체크리스트

• 배포 채널, 버전
  - Stable + MinimumVersion 를 위주로 결정
• 설치 경로
  - 플랫폼별 표준 조합 확정
  - Windows, Linux, MacOS 등
  - MDM, Ansible
• 미러
  - 필요 여부와 서명 배포 확인
  - 폐쇄망, 감사 요구 사항
• 정책 파일
  - Managed-Settings 초판과 배포 채널
• 롤백
  - 이전 버전 재설치 절차 문서화
  - 버전 지정 설치 활용

 

1.3. Security - 공급자, 자격증명

공식 Admin-Setup 권고 기준

• Teams / Enterprise
  - Claude.ai 와 통합 관리
  - 좌석제(인원할당), 인프라 불필요, 기본 권장
• Claude Console
  - 파이프라인 중심 조직
  - API 우선, 종량제 과금
• Amazon Bedrock
  - AWS 표준 기업
  - AWS 컴플라이언스와 과금 상속
• 혼합
  - 중앙 로깅 요구 시
  - LLM Gateway 로 단일 엔트포인트 구성

 

인증 우선순위

- 챕터 1 내용 복습

1. CLAUDE_CODE_USE_BEDROCK
   - 공급자 강제 스위치 변수
2. ANTHROPIC_API_KEY
   - 환경 변수 키, CI 와 서버 자동화 경로
3. apiKeyHelper
   - settings 의 동적 키 헬퍼 스크립트
   - 볼트 연동 지점
4. OAuth 토큰
   - Setup-Token 장기 토큰
   - Claude.ai 로그인 세션

Claude Platform on AWS

- Anthropic 운영 API 를 AWS 인증으로 처리

- Claude API 를 AWS IAM 인증과 Marketplace 과금으로 쓰는 경로

- 최신 기능 속도와 AWS 거버넌스 장점

• 구조
  - 엔드포인트 - Anthropic
  - 인증/과금 - AWS
• IAM 접근 통제
  - 역할 기반 접근
  - 정적 키 불필요
• Marketplace
  - AWS 청구서로 통합
  - 조달 절차 단순화
• Bedrock 선택 시점
  - 최신 기능 우선 + AWS 를 통한 과금이 필요할 경우

 

API Key 분배의 위험성

- 키 분배는 유출, 이직, 회전의 3중 부담

- 사람에게 SSO, 기계는 Vault 와 Helper가 원칙

• 정적 키 부담 사항
  - 커밋, 로그, 채팅을 통한 유출 경로 위험
  - 퇴사 시 회수 불가, 전수 회전 필요
  - 누가 썼는지 확인 불가
  - 감사 대응 시 증적 공백

• 대안
  - 사람: SSO 단기 토큰
  - 기계: Secrets Manager + apiKeyHelper
  - CI: OIDC 페더레이션, Setup-Token 최소화
  - 환경변수 하드코딩 전면 금지 정책

 

• apiKeyHelper / Vault 통합
  - API Key 하드코딩 탈피
  - 키 로테이션 자동화
  - CloudTrail 을 통한 감사 추적 가능

# ~/.claude/settings.json
{
  "apiKeyHelper": "/opt/claude/get-key.sh",
  "env": {
    "CLAUDE_CODE_API_KEY_HELPER_TTL_MS": "300000"
  }
}

# /opt/claude/get-key.sh
#!/bin/bash
aws secretsmanager get-secret-value \
  --secret-id claude/team-api-key \
  --query SecretString \
  --output text

자격증명 회전 체계

• 이중화
  - 신규 키 발급
  - 볼트에 병행 저장
• 전환
  - 볼트 포인터를 신규 키로 변경
• 관찰
  - TTL 경과 후 기존 키 호출 수 확인 (0)
• 폐기
  - 기존 키 비활성화
  - 감사 기록

PrivateLink / VPC Endpoint

- 인터넷 없이 Bedrock 호출 가능

- 폐쇄망 요건, 데이터 경로 통제 요구

• 엔드포인트
  - bedrock-runtime 인터페이스 엔드포인트 생성
• DNS 사설 해석
  - Private DNS 활성으로 SDK 무수정 전환
• 정책 결합
  - 엔드포인트 정책으로 호출 가능 모델, 주체 제한
• 경로 증명
  - VPC Flow Logs 로 트래픽 경로 증적

네트워크 보안

• 필수 아웃바운드 도메인
  api.anthropic.com - 추론 API, Bedrock 경로는 불필요
  claude.ai - 구독 로그인, 서버 관리 설정 수신
  downloads.claude.ai - 설치 자산, 패키지 저장소, 자동 갱신
  statsig 계열 - 기능 플래그 수신
  sentry 계열 - 오류 리포트 송신
  클라우드 엔드포인트 - bedrock-runtime..amazonaws.com 등

• DLP 훅 / 유출 패턴 차단
  - preToolUse 훅에 등록하여 차단

# /opt/claude/dlp.sh
#!/bin/bash
# PreToolUse DLP: AWS Access Key ID 패턴을 도구 입력에서 차단
INPUT=$(cat)
if echo "$INPUT" | grep -qE 'AKIA[0-9A-Z]{16}'; then
  echo "Blocked by DLP: AWS Access Key ID detected in tool input" >&2
  exit 2
fi
exit 0

// managed-settings.json
{
  "permissions": {
    "allow": ["Read(**)", "Grep", "Glob", "Bash(npm test:*)"],
    "ask": ["Edit(**)", "Write(**)"],
    "deny": ["Bash(rm -rf:*)", "Read(./.env)", "Read(./.env.*)"]
  },
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash|Edit|Write",
      "hooks": [{ "type": "command", "command": "/opt/claude/dlp.sh" }]
    }]
  },
  "companyAnnouncements": [
    "[Corp Policy] DLP Hook 활성화됨. AWS 키는 코드에 쓸 수 없습니다."
  ]
}

 

1.4. Governance, Policy

Managed Settings 채널

1. Server-managed : claude.ai 어드민 콘솔에서 배포
2. plist / HKLM : PC 기반
3. 파일 기반 : /etc/claude-code/managed-settings.json 등
4. HKCU : 사용자 레지스트리, 권한 상승 불필요

Server-managed 상세

- 콘솔에서 인프라 없이 바로

- 인증 시점에 기기로 다운로드되고, 활성 세션 중 매시간 갱신

- Teams, Enterprise 플랜 전용

• 도달 시점
  - 로그인 인증 시 수신
  - 세션 중 시간 단위 자동 갱신
• No Infra
  - MDM 이나 파일 배포 파이프라인 없이 콘솔에서 진행
• 플랜 제약
  - Teams, Enterprise 전용
• 혼합 전략
  - 타 공급자 병행 조직은 파일, plist 풀백을 함께 배포

 

• 예시
  - deny 설정
  - bypass 차단 - 우회모드 봉쇄
  - sandbox 도메인 통제
  - env 강제를 통한 공급자 변경 (Bedrock)

# /etc/claude-code/managed-settings.json
{
  "permissions": {
    "deny": [
      "Read(./.env*)",
      "Bash(rm -rf:*)",
      "Bash(curl * | bash:*)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": [
        "api.anthropic.com",
        "*.corp.example"
      ]
    }
  },
  "allowedMcpServers": [
    "github",
    "corp-wiki"
  ],
  "minimumVersion": "2.1.190",
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1"
  }
}

{
  "permissions": {
    "allow": ["Read(**)", "Grep", "Glob", "Bash(npm test:*)"],
    "ask": ["Edit(**)", "Write(**)"],
    "deny": ["Bash(rm -rf:*)", "Read(./.env)", "Read(./.env.*)"]
  },
  "companyAnnouncements": [
    "[Corp Policy] Claude Code managed settings 적용됨. .env 읽기는 금지됩니다."
  ]
}

 

병합 규칙

- Managed 우선, 배열은 합쳐짐

- permissions.allow, deny 는 모든 규칙이 병합

잠금 통제 설정

• alowManagedPermissionRulesOnly
  - managed 규칙만 유효, 개인 allow 설정 무시
  - 고수준 통제 환경
• disableBypassPermissionsMode
  - --dangerously-skip 우회 봉쇄
  - 전사 기본 권장
• alowManagedHooksOnly
  - managed 훅만 로드
  - 개별 훅 주입 차단
• allowdHttpHookUrls
  - HTTP 훅 목적지 허용 목록
  - 웹훅 유출 통제
• strict/blockedMarketplaces
  - 플러그인 마켓 소스 통제
  - 공급망 방어
• minimumVersion
  - 구버전 강제 상향
  - 보안 픽스 하한

MCP / 마켓플레이스 통제

• alowedMcpServers
  - 승인 서버 목록
  - 사내 승인 절차 연동
• deniedMcpServers
  - 명시 차단 목록
  - 사고 대응 시 즉시 배포
• alowManagedMcpServersOnly
  - managed 정의 서버만 연결
  - 최고 수준 통제
• strictKnownMarketplaces
  - 알려진 마켓만 추가 허용
  - 플러그인 공급망
• blockedMarketplaces
  - 특정 마켓 차단
  - 위험 소스 격리

권한 패턴 설계 전략

- deny 는 좁고 단단하게, allow 는 넓고 명시적으로

• managed deny (최소, 불변)
  - 파괴 명령: rm -rf, 디스크 포맷류
  - 자격증명 파일 읽기: .env, 키 경로
  - 파이프 실행: curl | bash 패턴
  - IAM 변조 등 권한 상승 명령
• allow 와 회색 지대
  - 빌드, 테스트, 린트 명령 명시 allow
  - git 조회 계열 전면 allow
  - push, 배포는 ask 로 확인

감사 훅 설정

- 누가 무엇을 실행했는지 감사

• preToolUse 활용
  - Bash, Write, Edit 감사
  - exit 0 유지 - 로그만 확인, 실제 차단 X

{
  "allowManagedHooksOnly": true,  // ← 관리형만 허용
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Edit|Write",  // ← 세 도구만 감시
        "hooks": [{
          "type": "command",
          "command": "/opt/claude/audit.sh"
        }]
      }
    ]
  }
}

정책 업데이트 워크플로

- Claude 정책도 코드처럼 관리

1. PR 제안
   - 정책 저장소에 변경 PR, 사유 기록
2. 시뮬레이션
   - auto-mode test
   - 스테이징 기기 검증
3. 링 배포
   - 파일럿 링부터 채널별 배포
4. 관측
   - 차단 로그, 문의량 모니터
5. 전사 확정
   - 롤백 태그 유지, 공지

 

1.5. 모니터링 / 비용

• 사용량 모니터링
  - OTel 로 세션, 도구, 토큰 송출
  - 전 공급자 지원
• Analytics 대시보드
  - 사용자별 지표, 기여 추적
  - Anthropic 경로 전용
• Cost Tracking
  - 지출 한도, 사용 귀속
  - Anthropic 경로 전용
• 클라우드 경로
  - Cost Explorer, GCP Billing, Azure CM
  - 과금 데이터 직접 활용
• 대시보드 주소
  - claude.ai/analytics/claude-code

OTel 설정

- 관리 설정으로 전사 계측

{
  "env": {
    // 1️⃣ 텔레메트리 활성화
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",

    // 2️⃣ 내보낼 데이터 종류
    "OTEL_METRICS_EXPORTER": "otlp",      // 메트릭
    "OTEL_LOGS_EXPORTER": "otlp",          // 로그
    // "OTEL_TRACES_EXPORTER": "otlp",     // 분산 추적

    // 3️⃣ 전송 프로토콜 + 수집기 주소
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc", // gRPC (HTTP/JSON도 가능)
    "OTEL_EXPORTER_OTLP_ENDPOINT": 
      "http://otel-collector.corp.example:4317",

    // 4️⃣ 리소스 태깅 (필터/집계용)
    "OTEL_RESOURCE_ATTRIBUTES":
      "department=platform,team=payments"
  }
}

 

관측 대상

• 세션 - 세션 수, 활성 시간
• 토큰 - 입출력, 캐시 읽기/생성
• 비용 - 추정 비용 카운터
• 도구 - 도구별 호출 수, 승인/거부
• 코드 변화 - 수정 라인, 커밋, PR
• 이벤트 - 프롬프트 제출 등 로그

 

SIEM 연계

• 경로 - Collecter에서 Splunk, OpenSearch 로 분기
• 결합 - 감사 훅 로그와 사용자 키로 조인
• 탐지 규칙 - 거부 급증, 심야 대량 토큰, 민감 경로 접근 등
• 대응 연결 - 티켓 자동 발부, deniedMcpServers 긴급 배포

 

Analytics 대시보드

- 사용자별 지표와 기여 추적 대시보드

• 사용자별 - 활성 사용자, 세션, 수용률 등 개인 단위 지표
• 기여 추적 - 커밋, PR 기여 등 성과 관점 지표
• 무구축 - 콘솔 포함 기능, 파이프라인 불필요
• 혼합 - Bedrock 병행 시 OTel 대시보드로 보완

 

클라우드 비용 가시화

- Bedrock 사용료는 AWS 에 그대로 과금

• 서비스 단위 - Bedrock 서비스, 모델 차원 필터
• 태그 전략 - 앱 추론 프로파일에 비용 태그 부여
• 부서 배분 - 태그, 계정 분리로 차지백 리포트 구성
• 일 단위 추적 - 일별 비용 그래프로 추세와 급변 감시

 

비용 최적화 전략

1. 모델 배분
   - haiku - 탐색 위주
   - sonnet - 메인
   - opus - 선별적 사용
2. 캐시 활용
   - 프롬프트 캐시 적중 관리
   - fork 의 캐시 공유
3. 컨텍스트 위생
   - /clear 습관
   - compact 임계 조정
4. 서브 에이전트
   - 고볼륨 출력 격리로 메인 토큰 절약
5. 배치 시간대
   - 무인 작업은 야간 예약으로 피크 회피
6. 한도 계층
   - 그룹 기본 + 개인 예외

 

이상 사용 감지

• 토큰 급증 - 개인 일 사용량이 평균 3배 초과
• 심야 대량 - 비업무 시간대 지속 호출
• 거부 급증 - 정책 거부 이벤트 단기 폭증
• 신규 목적지 - 허용 밖 도메인, MCP 시도 반복

 

1.6. Audit - 신원, 데이터, 컴플라이언스

• Claude 계정 레벨
  - SSO, SCIM 프로비저닝, 좌석 배정
  - Enterprise Administrator Guide 절차
  - claude.ai 콘솔에서 관리
  - Teams, Enterprise 플랜 대상
• 클라우드 IAM 레벨
  - Bedrock 호출 권한과 그룹 매핑
  - Identity Center, Workforce ID, Entra
  - Permission Set 이 실권한
  - Gateway 경유 시 OIDC 가 흡수

 

클로드 데이터 정책

• 클로드 학습 사용 여부 - Teams, Enterprise, API, 클라우드 경로는 학습 미사용
• 보존 - 경로별 retention, 공급자 정책 상속
• ZDR - 요청 완료 후 무저장, Enterprise 제공
• 요청 단위 감사 - 필요 시 LLM Gateway 로 중앙 로깅
• 로컬 데이터 - 세션 트랜스크립트로 30일 기본 정리

 

SOC2, ISO 27001 매핑

• 접근 통제 - SSO, Permission Set, 그룹 매핑
• 변경 관리 - Policy as Code, PR 리뷰, 링 배포
• 로깅, 감시 - CloudTrail, OTel, 감사 훅, SIEM
• 공급망 - GPG 서명, 마켓플레이스 통제
• 데이터 보호 - 학습 미사용, ZDR, 암호화 전송
• 가용성 - 게이트웨이 수평 확장, 버전 하한

 

2. Claude Apps Gateway

2.1. Why Gateway??

- Bedrock 직접 연결은 인증과 과금을 상속하지만, 조직 로그인 경험과 그룹별 모델 통제, 개인 지출 한도는 어려움

• Bedrock 직결에서 어려운 것
  - 개발자별 지출 한도 실시간 강제
  - IdP 그룹별 모델 접근 차등
  - 조직 표준 로그인 UX
  - 요청 단위 중앙 텔레메트리
• Apps Gateway 가 충족하는 것
  - 일, 주, 월 한도를 Admin API 로 설정, 즉시 강제
  - 그룹 → 모델 라우팅 규칙
  - OIDC SSO 로그인 플로우
  - OTLP 로 전 요청 관측

 

2.2. 아키텍처 / gateway.yaml 구성

• Listener + TLS
  - 수신 포트와 인증서
  - 조직 도메인으로 서비스
• OIDC + Session
  - IdP 연동 로그인
  - 세션 저장은 Postgres
• Policy
  - Managed 정책, 그룹 매핑, 지출 한도 판정
• Model Routing
  - 요청 모델을 그룹 규칙에 따라 허용, 치환
• Upstream
  - Bedrock, Agent Platform, Foundry 로 전달

SSO 로그인

# 클라이언트는 게이트웨이만 바라봄
export ANTHROPIC_BASE_URL=https://claude-gw.corp.example

# 로그인 > 조직 IdP 로그인
claude

 

그룹별 모델 라우팅

- IdP 그룹이 모델 접근 결정

# gateway.yaml
routing:
  groups:
    - match: "eng-platform"
      allowedModels: [opus, sonnet, haiku]
    - match: "eng-default"
      allowedModels: [sonnet, haiku]
      rewrite: { opus: sonnet } # 요청 치환 (opus 요청을 sonnet 으로 변경)
    - match: "contractors"
      allowedModels: [haiku]

지출 한도 / Admin API

- 개발자별 일, 주, 월 한도를 강제

- 한도 도달 시 요청 거부

# 한도 설정
curl -X PUT https://claude-gw.corp.example/admin/limits \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{ "subject": "user:jdoe", "period": "month", "usd": 300 }'

 

2.3. 배포 및 운영

- Kubernetes, Cloud Run 표준 경로

• 구성요소
  - 게이트웨이 컨테이너 + Postgres 세션 저장소
• 사전 등록 IDP
  - OIDC 클라이언트 등록
  - Redirect URI 지정
• 운영 루틴
  - 헬스체크 엔드포인트
  - 시크릿 회전
  - 무중단 업그레이드
• 가용성
  - Stateless 수평 확장
  - 세션은 Postgres 담당

OTLP Telemetry

• OTLP 송출
  - 게이트웨이가 전 요청의 메트릭, 트레이스를 표준 송출
• 차원
  - 사용자, 그룹, 모델, 토큰, 판정 결과 태그
• 수집처
  - CloudWatch, Datadog 등
• 클라이언트 결합

 

2.4. Apps Gateway vs LLM Gateway

- 일반 LLM Gateway 는 범용 프록시

- Apps Gateway 는 Claude Code 조직 운영에 특화

• 일반 LLM Gateway (LiteLLM 등)
  - 다중 벤더 추상화 목적
  - Claude Code 정책 모델 미인지
  - 한도, 라우팅을 직접 구현
  - 범용 프록시 유지보수 부담
• Claude Apps Gateway
  - Claude Code 전용 설계
  - Managed 정책과 자연 결합
  - SSO, 라우팅, 한도가 내장 완제품
  - 공식 배포, 운영 문서 제공