Google Cloud에서 Claude API 연결하기: IAM 인증부터 첫 요청까지

Google Cloud에서 Anthropic 관리형 Claude API를 호출하려면 Marketplace 구독과 서비스 활성화, IAM 호출 권한, 로컬 인증 설정이 필요합니다. 이 글은 Windows PowerShell과 Python SDK로 첫 메시지를 보내는 절차를 다룹니다.

Google 관리형에서 사용하는 AnthropicVertex와는 연결 방식이 다릅니다. 여기서는 AnthropicGoogleCloud 클라이언트를 사용합니다.

먼저 구분할 용어

인증과 권한을 나누어 이해하면 로그인 후 발생하는 오류를 좁히기 쉽습니다.

용어이 글에서의 의미

IAM	Google Cloud에서 호출 주체의 접근 권한을 관리하는 체계
ADC	SDK가 사용할 Google 인증 정보를 찾는 방식
Workspace	Claude 요청의 대상이 되는 작업 공간

1. 구독과 프로젝트 설정

Anthropic의 설정 문서에 따라 Google Cloud Marketplace에서 Claude Models on Google Cloud (Anthropic managed)를 구독합니다. 구매를 마친 뒤, 호출할 프로젝트에서 다음 두 서비스를 활성화합니다.

• claude.googleapis.com
• anthropic-managed-claude.cloudpartnerservices.goog

이 과정에는 결제 계정의 Marketplace 구매 권한과 프로젝트의 서비스 활성화 권한이 필요합니다. 이어서 Claude 페이지의 Activate로 Anthropic 조직을 설정합니다.

Open Claude Console로 들어가 Settings > Workspaces에서 wrkspc_로 시작하는 ID를 확보합니다. 프로젝트 ID도 함께 준비하세요. 콘솔 진입에는 사전정의 역할 중 roles/claude.admin이 필요하므로, 호출만 담당한다면 관리자에게 Workspace ID를 요청할 수 있습니다.

2. IAM 역할과 ADC 로그인

호출할 사용자 또는 서비스 계정에 프로젝트 수준의 roles/claude.user를 부여합니다. Anthropic IAM 문서에 따르면 roles/claude.viewer로는 메시지를 보낼 수 없습니다. 콘솔 관리 권한과 API 호출 권한을 구분해 부여하세요.

로컬에서는 Google Cloud CLI와 Python을 준비한 다음 PowerShell에서 ADC 로그인을 실행합니다.

gcloud auth application-default login

로그인할 때는 앞에서 호출 권한을 받은 계정을 선택합니다. Google 인증 문서에 따르면 일반 gcloud auth login과 ADC 로그인은 별개입니다. 이 명령은 기존 로컬 ADC를 덮어쓰므로 이미 다른 프로젝트를 개발 중이라면 사용하는 계정을 확인하세요.

3. Python SDK로 첫 메시지 보내기

아래는 공식 문서 기반의 실행 미검증 예제입니다. 실제 API 호출과 청구 결과는 검증하지 않았습니다.

PowerShell에서 SDK를 설치하고, 두 값을 자신의 프로젝트 ID와 Workspace ID로 바꿉니다. 환경변수는 현재 PowerShell 세션에 적용됩니다.

python -m pip install -U "anthropic[google_cloud]"
$env:ANTHROPIC_GOOGLE_CLOUD_PROJECT = "my-project-id"
$env:ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID = "wrkspc_your_workspace_id"

다음 코드를 first_request.py로 저장합니다.

from anthropic import AnthropicGoogleCloud

client = AnthropicGoogleCloud()
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "IAM과 ADC의 차이를 두 문장으로 설명해 주세요."}
    ],
)
print(message)

모델명은 공식 첫 요청 예제의 값입니다. 조직에서 사용할 수 있는 모델인지 확인하고 실행하세요. 이 연결 방식에서는 Google 인증 정보를 사용하므로 Anthropic API 키를 입력하는 단계가 없습니다.

환경변수를 설정한 같은 PowerShell에서 파일을 실행합니다.

python .\first_request.py

예제는 반환된 메시지 객체를 출력하도록 작성했습니다. 결제는 Marketplace 구독을 통해 처리되므로 호출 전에 이용 요금도 확인하세요.

4. 로그인했는데 요청이 막힐 때

403이라면 호출 주체와 IAM 역할을 먼저 확인합니다. Anthropic IAM 문서는 필요한 권한이 없는 호출에 403을 반환한다고 설명합니다. 로그인 성공만으로 메시지 전송 권한이 생기지는 않습니다.

점검 대상확인할 내용

IAM 역할	실제 호출 계정에 roles/claude.user가 있는지 확인합니다.
ADC 선택	GOOGLE_APPLICATION_CREDENTIALS가 설정되어 있으면 해당 파일이 로컬 ADC보다 우선합니다.
서비스 활성화	요청할 프로젝트에 앞서 나온 두 서비스가 모두 활성화되어 있는지 확인합니다.
연결 방식	Google 관리형의 AnthropicVertex 예제를 섞어 쓰지 않았는지 확인합니다.

인증 오류를 해결할 때는 SDK가 읽는 자격증명과 권한을 받은 계정이 같은지부터 맞추세요. 운영 환경으로 옮길 때는 연결된 서비스 계정과 필요한 최소 권한을 사용하는 방식으로 전환합니다.

참고 링크

• Anthropic — Claude Models on Google Cloud (Anthropic managed)
• Google Cloud — How Application Default Credentials works