Claude Platform Docs
관리자암호화 키

CMEK용 Google Cloud KMS 구성

Google Cloud KMS를 사용하여 조직에 암호화 키를 제공합니다.

Configure with the /claude-api skill in Claude Code
claude "/claude-api help me configure a customer-managed encryption key with Google Cloud KMS"

이 가이드는 Google Cloud KMS 키를 Anthropic 조직의 "customer-managed encryption key"(고객 관리 암호화 키), 즉 CMEK로 구성하는 과정을 안내합니다.

사전 요구 사항

  • 결제가 활성화된 Google Cloud 프로젝트.
  • Cloud KMS API 활성화(cloudkms.googleapis.com).
  • KMS 키 링과 키를 생성하고 이에 대한 IAM 정책을 설정할 수 있는 권한(roles/cloudkms.admin 또는 이에 상응하는 권한).
  • 조직의 Anthropic Admin API 키.
  • gcloud CLI 설치 및 인증 완료.
  • 프로젝트에 대해 Cloud KMS 데이터 액세스 감사 로그 활성화(IAM & Admin > Audit Logs > Cloud Key Management Service에서 DATA_READ 및 DATA_WRITE 선택). 이 로그는 기본적으로 꺼져 있으며, 활성화하지 않으면 Anthropic의 암호화 및 복호화 작업이 Cloud Logging에 항목을 생성하지 않습니다.

Anthropic 서비스 계정 이메일

Anthropic이 여러분의 암호화 키를 사용하도록 하려면, Anthropic의 서비스 계정에 데이터 암호화에 사용할 수 있는 키를 제공해야 합니다. Anthropic CMEK용 서비스 계정 이메일은 다음과 같습니다:

anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com

암호화 키 설정

  1. 키 링 생성 또는 선택

    재사용할 키 링이 이미 있다면 이 단계를 건너뛰세요. 키 링은 리전 단위입니다. 구성 중인 Anthropic 지역과 일치하는 us-east5와 같은 단일 리전 US 위치를 선택하세요. us 및 global과 같은 멀티 리전 위치는 지원되지 않습니다.

    gcloud kms keyrings create <your-keyring-name> \
  --project=<your-project-id> \
  --location=<region>

  2. 암호화 키 생성

    ENCRYPT_DECRYPT 용도의 대칭 키를 생성하세요. Anthropic은 HSM 보호를 강력히 권장합니다. Cloud KMS HSM 키는 FIPS 140-2 Level 3 검증을 받았으며, 소프트웨어 키 대비 비용 차이가 작습니다.

    gcloud kms keys create <your-key-name> \
  --project=<your-project-id> \
  --location=<region> \
  --keyring=<your-keyring-name> \
  --purpose=encryption \
  --protection-level=hsm

    대신 소프트웨어 보호를 사용하려면 --protection-level=hsm을 생략하세요. 이 가이드의 나머지 내용은 변경되지 않습니다.

    Google Cloud Console에서도 키를 생성할 수 있습니다. 키 링을 열고 Create key를 클릭한 다음 Generated key를 선택하고, 용도와 알고리즘을 대칭 암호화 및 복호화로 설정한 뒤 보호 수준에서 HSM을 선택하세요.

    HSM 보호 수준과 Symmetric encrypt/decrypt 용도가 설정된 Google Cloud KMS Create key 페이지.
    HSM으로 보호되는 대칭 암호화/복호화(Symmetric encrypt/decrypt) 키를 생성합니다.

  3. Anthropic 서비스 계정에 키 액세스 권한 부여

    두 개의 키 수준 IAM 바인딩이 필요합니다. 둘 다 프로젝트 전체나 키 링 전체가 아닌 단일 암호화 키로 범위가 지정됩니다.

    암호화 및 복호화 권한은 Anthropic이 워크스페이스 데이터를 보호하는 데이터 키를 암호화하고 복호화하는 데 사용합니다(봉투 암호화, envelope encryption):

    gcloud kms keys add-iam-policy-binding <your-key-name> \
  --project=<your-project-id> \
  --location=<region> \
  --keyring=<your-keyring-name> \
  --member="serviceAccount:anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com" \
  --role=roles/cloudkms.cryptoKeyEncrypterDecrypter

    뷰어 권한은 Anthropic이 시작 시 키의 용도와 알고리즘을 검증하기 위해 수행하는 메타데이터 읽기(cryptoKeys.get)에 사용됩니다:

    gcloud kms keys add-iam-policy-binding <your-key-name> \
  --project=<your-project-id> \
  --location=<region> \
  --keyring=<your-keyring-name> \
  --member="serviceAccount:anthropic-cmek-client-us@gcp-anthropic-cmek-clients.iam.gserviceaccount.com" \
  --role=roles/cloudkms.viewer

    Console에서는 키를 선택하고 Permissions 패널을 연 다음 Grant access를 클릭하고, Cloud KMS CryptoKey Encrypter/Decrypter 및 Cloud KMS Viewer 역할을 모두 지정하여 서비스 계정을 추가하세요. 권한 부여가 이 키에만 범위가 지정되도록, 키 링이나 프로젝트가 아닌 키의 권한 페이지에 있는지 확인하세요.

    Anthropic 서비스 계정에 Cloud KMS CryptoKey Encrypter/Decrypter 및 Viewer 역할이 할당된 Grant access 대화 상자.
    Anthropic 서비스 계정에 키 범위로 지정된 두 역할(Cloud KMS CryptoKey Encrypter/Decrypter 및 Viewer)을 모두 부여합니다.

  4. 전체 키 리소스 이름 기록

    키를 등록할 때 이 값을 Anthropic에 전달합니다. 형식은 다음과 같습니다:

    projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>

    다음 명령으로 조회하세요:

    gcloud kms keys describe <your-key-name> \
  --project=<your-project-id> \
  --location=<region> \
  --keyring=<your-keyring-name> \
  --format="value(name)"

    Console에서는 키의 세부 정보 페이지를 열고 Copy resource name을 클릭하세요.

    키의 작업 메뉴에서 Copy resource name 작업이 강조 표시된 Google Cloud 키 링 세부 정보.
    작업 메뉴에서 키의 전체 리소스 이름을 복사합니다(Copy resource name).

Anthropic에 키 등록

키를 등록하는 방법은 사용하는 제품에 따라 다릅니다.

  1. Anthropic에 키 등록

    암호화 키 설정의 전체 키 리소스 이름 기록 단계에서 얻은 리소스 이름을 사용하여 Admin API를 통해 외부 키 구성을 생성하세요.

    client = anthropic.Anthropic()

external_key = client.beta.organization.external_keys.create(
    display_name="<friendly-name>",
    geo="us",
    provider_config={
        "type": "gcp",
        "key_name": "projects/<your-project-id>/locations/<region>/keyRings/<your-keyring-name>/cryptoKeys/<your-key-name>",
    },
)

print(f"id: {external_key.id}")
print(f"display_name: {external_key.display_name}")

    응답에는 외부 키 ID가 포함됩니다:

    {
  "type": "external_key",
  "id": "ekey_<id>",
  "display_name": "<friendly-name>"
}

  2. 키 검증

    키에 대해 암호화 및 복호화 왕복 테스트를 실행하세요.

    client = anthropic.Anthropic()

validation = client.beta.organization.external_keys.validate("ekey_<id>")

print(f"status: {validation.status}")
print(f"error: {validation.error}")

    성공적인 응답은 다음과 같습니다:

    { "type": "external_key_validation", "status": "success", "error": null }

    검증이 실패하는 경우 일반적인 원인은 다음과 같습니다:

    • VPC Service Controls: 프로젝트에서 서비스 경계가 Cloud KMS를 보호하고 있다면, Anthropic이 키에 접근할 수 있도록 경계의 액세스 수준에 Anthropic을 추가하거나 키의 프로젝트를 제외하세요.
    • 도메인 제한 공유: constraints/iam.allowedPolicyMemberDomains 조직 정책이 Anthropic 서비스 계정 바인딩을 제거할 수 있습니다(앞의 참고 사항 참조). gcloud kms keys get-iam-policy <your-key-name> --project=<your-project-id> --location=<region> --keyring=<your-keyring-name>으로 바인딩이 존재하는지 확인하세요.
    • 비활성화되거나 폐기된 키 버전: 키의 기본 버전이 활성화되어 있으며, 비활성화되었거나 폐기 예정이거나 폐기된 상태가 아닌지 확인하세요.

  3. 워크스페이스에 키 연결

    키가 검증되면, 해당 워크스페이스에 요청을 보내기 전에 새 워크스페이스에 키를 연결하세요. 이미 요청을 받고 있는 워크스페이스의 경우 키가 적용되기까지 최대 하루가 걸릴 수 있습니다.

    client = anthropic.Anthropic()

workspace = client.beta.organization.workspaces.update(
    "<workspace-id>", external_key_id="ekey_<id>"
)

print(f"id: {workspace.id}")
print(f"external_key_id: {workspace.external_key_id}")

Terraform

코드형 인프라(infrastructure-as-code) 배포의 경우, 동일한 단계가 google 프로바이더의 google_kms_key_ring, google_kms_crypto_key, google_kms_crypto_key_iam_member 리소스에 대응됩니다.

Was this page helpful?