AI/Claude Code Doc(공식문서) 번역본

Claude Code 공식문서 리뷰-Deployment[4] : Microsoft Foundry의 Claude Code

안녕하세요! 갓대희입니다.

Claude Code Docs 공식 문서 >> Deployment 섹션의 내용 중 [Microsoft Foundry의 Claude Code]를 살펴 보려고 합니다.

https://code.claude.com/docs/en/microsoft-foundry

Claude Code on Microsoft Foundry - Claude Code Docs

Learn about configuring Claude Code through Microsoft Foundry, including setup, configuration, and troubleshooting.

code.claude.com

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다.

안녕하세요! 갓대희입니다.

Claude Code Docs 공식 문서 >> Deployment 섹션의 내용 중 [Microsoft Foundry의 Claude Code]를 살펴 보려고 합니다.

이번 섹션 부터는 영문, 한글번역본이 모두 공식문서로 존재하는 섹션이니 한글 문서를 편하게 참고 하셔도 될 것 같습니다.

https://code.claude.com/docs/en/microsoft-foundry

Claude Code on Microsoft Foundry - Claude Code Docs

Learn about configuring Claude Code through Microsoft Foundry, including setup, configuration, and troubleshooting.

code.claude.com

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

Microsoft Foundry에서 Claude Code 사용하기

Microsoft Foundry: Azure의 AI 개발 플랫폼
인증: API 키 또는 Microsoft Entra ID 지원
보안: 기업용 보안 및 규정 준수 기능 제공

용어 설명: Microsoft Foundry (Azure AI Foundry)
Microsoft Azure에서 제공하는 AI 개발 플랫폼으로, Claude를 포함한 다양한 AI 모델에 접근하고 배포할 수 있다. 기업용 보안 및 규정 준수 기능을 제공한다.

왜 Microsoft Foundry를 사용하는가?

실제 상황을 생각해보자

회사에서 이미 Microsoft Azure를 많이 쓰고 있다면, 기존 Azure 인프라에 Claude를 통합하는 것이 가장 자연스럽다.

예시 상황:
• Azure Active Directory로 팀 전체 인증을 관리 중
• Azure 구독으로 이미 여러 서비스 사용 중
• Azure의 보안 정책과 규정 준수 프레임워크를 따라야 함
• IT 팀이 Azure에 익숙하고, 기존 인프라를 활용하고 싶음

이런 경우 Anthropic API를 직접 쓰는 것보다 Microsoft Foundry를 통해 Claude를 쓰는 게 훨씬 편하다.

주요 장점

통합 인증: Azure AD (Entra ID)로 한 번에 관리
통합 결제: 기존 Azure 청구서에 포함 - 별도 계정/결제 불필요
RBAC 권한: Azure의 역할 기반 액세스 제어 활용
규정 준수: Azure의 보안/규정 준수 프레임워크 그대로 적용
네트워크 통합: 기존 Azure VNet, 프라이빗 엔드포인트 사용 가능

사전 요구사항

시작하기 전에 확인할 것

Azure 관리자나 IT 팀과 먼저 확인하면 시간을 많이 절약할 수 있다.

필수 요구사항

Azure 구독 액세스
- Microsoft Foundry (Azure AI Foundry)를 사용할 수 있는 구독
- 확인 방법: Azure Portal에서 구독 목록 확인
RBAC 권한
- Foundry 리소스를 생성하고 모델을 배포할 권한
- 보통 Contributor 또는 Owner 역할 필요
- 권한이 없다면 Azure 관리자에게 요청

선택 사항 (있으면 편리함)

Azure CLI - 터미널에서 Azure 관리하고 싶다면

# macOS/Linux
brew install azure-cli

# Windows
choco install azure-cli

설정 (3단계 완료)

예상 소요 시간

처음 설정: 약 15-20분 (Azure 리소스 생성 시간 포함)
이후 다른 프로젝트: 5분 (환경 변수만 설정)

1단계: Microsoft Foundry 리소스 프로비저닝

💡 처음이라면 Azure Portal에서 하자

Azure CLI로도 가능하지만, 처음이라면 웹 포털이 훨씬 직관적이다.

Microsoft Foundry 포털 이동
- https://ai.azure.com 접속
- Azure 계정으로 로그인
새 리소스 (Resource) 생성
- "Create new resource" 또는 "+ 새로 만들기" 클릭
- 리소스 이름 입력 (예: my-claude-foundry)
- 이 이름을 어딘가에 기록해두자! 나중에 환경 변수에 쓴다
Claude 모델 배포 (Deployment) 생성
- 리소스 안에서 "Deployments" 섹션으로 이동
- 사용하려는 모델마다 배포 생성:
  - claude-sonnet-4-5 (권장 - 가장 많이 씀)
  - claude-haiku-4-5 (빠른 작업용)
  - claude-opus-4-1 (고급 작업용, 선택)
- 배포 이름도 정확히 기록!

2단계: Azure 자격 증명 구성

어떤 방법을 선택해야 할까?

옵션 A (API 키): 빠르고 간단. 개인 개발자나 테스트용으로 적합
옵션 B (Entra ID): 더 안전하고 팀 단위 관리에 좋음. 프로덕션 환경 권장

Claude Code는 두 가지 인증 방법을 지원한다:

옵션 A: API 키 인증 (빠른 시작)

Microsoft Foundry 포털에서 리소스로 이동
Endpoints and keys 섹션으로 이동
API Key 복사
환경 변수 설정:

export ANTHROPIC_FOUNDRY_API_KEY=your-azure-api-key

옵션 B: Microsoft Entra ID 인증 (권장)

ANTHROPIC_FOUNDRY_API_KEY가 설정되지 않으면 Claude Code는 Azure SDK 기본 자격 증명 체인을 자동으로 사용한다.

장점

API 키를 관리할 필요 없음
팀원들의 액세스를 Azure RBAC로 중앙 관리
키 유출 걱정 없음 (Azure AD 토큰 자동 갱신)

로컬 개발 환경: Azure CLI로 간단히 로그인

# 터미널에서 실행
az login

# 로그인 성공하면 브라우저 창이 뜨고 자격 증명 입력
# 이후 Claude Code가 자동으로 Azure AD 토큰 사용

프로덕션/CI/CD 환경: Managed Identity 또는 Service Principal 사용

참고
Microsoft Foundry 사용 시 /login 및 /logout 명령이 비활성화된다. 인증은 Azure 자격 증명을 통해 처리된다.

3단계: Claude Code 구성

다음 환경 변수를 설정하여 Microsoft Foundry를 활성화한다:

# Microsoft Foundry 통합 활성화
export CLAUDE_CODE_USE_FOUNDRY=1

# Azure 리소스 이름 ({resource}를 실제 리소스 이름으로 대체)
export ANTHROPIC_FOUNDRY_RESOURCE={resource}
# 또는 전체 기본 URL 제공:
# export ANTHROPIC_FOUNDRY_BASE_URL=https://{resource}.services.ai.azure.com

# 모델을 리소스의 배포 이름으로 설정
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-5'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-1'

팁
모델 구성 옵션에 대한 자세한 내용은 모델 구성 문서를 참조한다.

Azure RBAC 구성

Azure AI User 및 Cognitive Services User 기본 역할에는 Claude 모델 호출에 필요한 모든 권한이 포함되어 있다.

더 제한적인 권한을 위해 다음 권한으로 커스텀 역할 생성:

{
  "permissions": [
    {
      "dataActions": [
        "Microsoft.CognitiveServices/accounts/providers/*"
      ]
    }
  ]
}

문제 해결

에러 1: 토큰 획득 실패

에러 메시지

Failed to get token from azureADTokenProvider: ChainedTokenCredential authentication failed

원인: Azure AD 인증이 제대로 구성되지 않았다.

해결 방법:

빠른 해결: API 키로 전환

export ANTHROPIC_FOUNDRY_API_KEY=your-api-key

Azure AD 사용: Azure CLI 로그인 확인

az login
az account show  # 로그인된 계정 확인

에러 2: 리소스를 찾을 수 없음

에러 메시지

Resource not found

원인: ANTHROPIC_FOUNDRY_RESOURCE 이름이 틀렸다.

확인 방법:

Azure Portal에서 리소스 이름 다시 확인
환경 변수 출력: echo $ANTHROPIC_FOUNDRY_RESOURCE
오타가 없는지 확인 (대소문자 구분!)

에러 3: 권한 거부

에러 메시지

Insufficient permissions

원인: RBAC 역할이 없거나 부족하다.

해결: Azure 관리자에게 다음 중 하나를 요청

Azure AI User 역할
또는 Cognitive Services User 역할

다음 단계 - 상황별 가이드

Foundry 설정을 마쳤다면?

이제 실제로 Claude Code를 써보거나, 팀 전체에 배포하거나, 추가 보안 설정을 할 차례다. 아래에서 현재 상황에 맞는 다음 단계를 선택하자.

문서	언제 유용한가?
엔터프라이즈 네트워크 구성	회사 네트워크에서 프록시를 써야 하거나, 사내 CA 인증서가 필요하거나, 방화벽 설정이 필요한 경우
샌드박싱	AI가 실행하는 코드의 파일 시스템/네트워크 접근을 제한하고 싶을 때
Microsoft Foundry 공식 문서	Azure AI Foundry의 더 자세한 설정이나 고급 기능을 알고 싶을 때
사용 가능한 모델 목록	Foundry에서 어떤 Claude 모델을 쓸 수 있는지 확인하고 싶을 때
Azure AI Foundry 가격	Foundry를 통한 Claude 사용 비용을 미리 계산하고 싶을 때
Azure RBAC 권한 문서	Azure AI Foundry의 역할 기반 액세스 제어(RBAC)를 상세히 알고 싶을 때
Claude Code 공식 문서	Microsoft Foundry와 Claude Code 통합에 대한 공식 가이드

권장 학습 경로

지금 문서로 Foundry 기본 설정 완료
회사 네트워크 환경이라면 → 엔터프라이즈 네트워크 구성 확인
보안이 중요하다면 → 샌드박싱 활성화
이제 실제로 Claude Code 써보기!

빠른 시작 체크리스트

핵심 요약 (3줄)

Azure 사용자라면 Foundry로 Claude를 쓰는 게 통합 인증, 통합 결제 측면에서 유리
포털에서 리소스 + 모델 배포 생성 → 환경 변수 3개만 설정하면 끝
인증은 API 키(빠름) 또는 Entra ID(권장) 중 선택

단계 1: Azure Portal에서 리소스 생성 (5분)

☐ https://ai.azure.com 접속
☐ "Create new resource" 클릭 → 리소스 이름 정하기
☐ Deployments에서 Claude 모델 배포 생성
- claude-sonnet-4-5 (권장)
- claude-haiku-4-5 (빠른 작업용)
☐ 리소스 이름과 배포 이름 기록하기

단계 2: 환경 변수 설정 (3분)

☐ Foundry 활성화
```
export CLAUDE_CODE_USE_FOUNDRY=1
```

☐ 리소스 지정 (둘 중 하나)

# 방법 1: 리소스 이름 (간단)
export ANTHROPIC_FOUNDRY_RESOURCE=my-claude-foundry

# 방법 2: 전체 URL (고급)
export ANTHROPIC_FOUNDRY_BASE_URL=https://my-claude-foundry.services.ai.azure.com

☐ 인증 선택 (둘 중 하나)

# 옵션 A: API 키 (빠른 시작)
export ANTHROPIC_FOUNDRY_API_KEY=your-api-key

# 옵션 B: Entra ID (권장)
az login  # Azure CLI 설치 후

단계 3: RBAC 역할 확인 (Entra ID 사용 시)

☐ Azure 관리자에게 다음 중 하나의 역할 요청
- Azure AI User (권장)
- 또는 Cognitive Services User
☐ 역할 할당 확인: Azure Portal → IAM → Role assignments

단계 4: 테스트 (1분)

☐ Claude Code 실행
☐ 간단한 질문 던져보기 (예: "Hello, Claude!")
☐ 에러 없이 응답 오는지 확인

영구 설정하기

매번 export 치기 귀찮다면 ~/.bashrc 또는 ~/.zshrc에 추가하자:

export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=my-claude-foundry
export ANTHROPIC_FOUNDRY_API_KEY=your-api-key

저작자표시 비영리 변경금지 (새창열림)

'AI > Claude Code Doc(공식문서) 번역본' 카테고리의 다른 글

Claude Code 공식문서 리뷰-Deployment[6] : LLM 게이트웨이 구성(LLM gateway configuration) (0)	2026.01.02
Claude Code 공식문서 리뷰-Deployment[5] : 기업 네트워크 구성(Enterprise network configuration) (1)	2026.01.01
Claude Code 공식문서 리뷰-Deployment[3] : Google Vertex AI의 Claude Code(Claude Code on Google Vertex AI) (0)	2026.01.01
Claude Code 공식문서 리뷰-Deployment[1] : 엔터프라이즈 배포 개요(Enterprise deployment overview) (3)	2025.12.29
Claude Code 공식문서 리뷰-Build with Claude Code[8] : Troubleshooting (0)	2025.12.29

Contents

새소식

Claude Code 공식문서 리뷰-Deployment[4] : Microsoft Foundry의 Claude Code

왜 Microsoft Foundry를 사용하는가?

사전 요구사항

필수 요구사항

선택 사항 (있으면 편리함)

설정 (3단계 완료)

1단계: Microsoft Foundry 리소스 프로비저닝

2단계: Azure 자격 증명 구성

옵션 A: API 키 인증 (빠른 시작)

옵션 B: Microsoft Entra ID 인증 (권장)

3단계: Claude Code 구성

Azure RBAC 구성

문제 해결

에러 1: 토큰 획득 실패

에러 2: 리소스를 찾을 수 없음

에러 3: 권한 거부

다음 단계 - 상황별 가이드

빠른 시작 체크리스트

단계 1: Azure Portal에서 리소스 생성 (5분)

단계 2: 환경 변수 설정 (3분)

단계 3: RBAC 역할 확인 (Entra ID 사용 시)

단계 4: 테스트 (1분)

'AI > Claude Code Doc(공식문서) 번역본' 카테고리의 다른 글

당신이 좋아할만한 콘텐츠

티스토리툴바