고객 관리 암호화 키(CMEK)

기본적으로 Gemini Data Analytics는 저장 중인 고객 콘텐츠를 암호화합니다. Gemini Data Analytics는 개발자의 추가 작업 없이 자동으로 암호화를 처리합니다. 이 옵션을 Google 기본 암호화라고 합니다.

암호화 키를 제어하려면 Cloud KMS에서 Gemini Data Analytics가 포함된 고객 관리 암호화 키(CMEK) 통합 서비스와 함께 CMEK를 사용하면 됩니다. Cloud KMS 키를 사용하면 보호 수준, 위치, 순환 일정, 사용 및 액세스 권한, 암호화 경계를 관리할 수 있습니다. Cloud KMS를 사용하면 감사 로그를 보고 키 수명 주기를 제어할 수도 있습니다. Google에서 데이터를 보호하는 대칭 키 암호화 키(KEK)를 소유하고 관리하는 대신 사용자가 Cloud KMS에서 이러한 키를 제어하고 관리할 수 있습니다.

CMEK로 리소스를 설정한 후 Gemini Data Analytics 리소스에 액세스하는 환경은 Google 기본 암호화 사용과 유사합니다. 암호화 옵션에 대한 자세한 내용은 고객 관리 암호화 키(CMEK)를 참조하세요.

이 페이지에서는 고객 관리 암호화 키 (CMEK)를 사용하여 Looker 데이터 소스가 있는 Conversational Analytics API에서 사용하는 데이터를 보호하는 방법을 설명합니다. Conversational Analytics API는 Gemini 데이터 분석 서비스 (geminidataanalytics.googleapis.com) 내의 제품입니다.

Conversational Analytics API 리소스의 CMEK

Conversational Analytics API 리소스에 CMEK를 구성하면 지정된 Cloud KMS 키가 저장 데이터를 암호화합니다. DataAgent 및 Conversation 리소스에 대해 별도로 CMEK를 구성할 수 있습니다.

CMEK는 리소스를 만들 때만 구성할 수 있습니다. CMEK를 사용하려면 DataAgent 또는 Conversation 리소스를 만들 때 kms_key 필드를 지정해야 합니다. 기존 리소스에는 Cloud KMS 키를 추가하거나 변경할 수 없습니다.

CMEK로 보호되는 대상

Conversational Analytics API의 CMEK는 다음과 같은 저장 데이터를 보호합니다.

DataAgent 리소스: data_analytics_agent의 staging_context, published_context, last_published_context 필드에 있는 모든 고객 핵심 콘텐츠입니다. 여기에는 system_instruction 및 example_queries와 같은 필드가 포함됩니다.
Conversation 리소스: 모든 메시지 및 상태 기록

다음 데이터는 고객의 CMEK 키로 암호화되지 않습니다. 대신 이 데이터는 Google 기본 암호화로 보호됩니다.

DataAgent 리소스: name, display_name, description, labels, create_time, update_time, delete_time, purge_time, kms_key 등의 메타데이터 필드
Conversation 리소스: name, agents, labels, create_time, last_used_time, kms_key 등의 메타데이터 필드

제한사항

Conversational Analytics API의 CMEK에는 다음과 같은 제한사항이 있습니다.

CMEK는 리소스를 만들 때 구성해야 합니다. 기존 리소스에 추가하거나 변경할 수 없습니다.
Cloud KMS 키와 Conversational Analytics API 리소스는 동일한 위치에 있어야 합니다. global 지역은 지원되지 않습니다.
Conversational Analytics API 리소스의 경우 CMEK는 us-east4 리전에서 지원됩니다.
Conversational Analytics API 리소스의 경우 Looker 데이터 소스에만 CMEK가 지원됩니다.
프로젝트 및 리전 내의 모든 Conversation 리소스에 대해 프로젝트당 리전당 하나의 CMEK만 사용할 수 있습니다.

시작하기 전에

대화형 분석 API와 함께 CMEK를 사용하려면 다음 단계를 완료하세요.

Google Cloud 콘솔 또는 Google Cloud CLI 내에서 필요한 API를 사용 설정합니다.
콘솔
Google Cloud 콘솔에서 Google Cloud 프로젝트에 다음 API를 사용 설정합니다.

Gemini 데이터 분석 API 사용 설정

Gemini for Google Cloud API 사용 설정

Cloud Key Management Service API 사용 설정

도움말: API를 사용 설정할 때는 Google Cloud 콘솔 페이지를 새로고침하여 사용 설정되었는지 확인해야 할 수 있습니다.
gcloud
Google Cloud CLI를 사용하여 다음 gcloud services enable 명령어를 실행하여 Gemini Data Analytics API, Gemini for Google Cloud API, Cloud Key Management Service API를 각각 사용 설정합니다.
```
gcloud services enable geminidataanalytics.googleapis.com --project=project_id
gcloud services enable cloudaicompanion.googleapis.com --project=project_id
gcloud services enable cloudkms.googleapis.com --project=project_id
```
이전 샘플 gcloud CLI 명령어에서 project_id를 Google Cloud 프로젝트 ID로 바꿉니다.
허용 목록에 프로젝트를 추가합니다.

Gemini 데이터 분석과 함께 CMEK를 사용하려면 Google Cloud 프로젝트가 허용 목록에 추가되어야 합니다. 프로젝트를 허용 목록에 추가하도록 요청하려면 GDA CMEK 허용 목록 추가 양식을 통해 프로젝트 ID를 제출하세요. 프로젝트를 허용 목록에 추가하는 데는 영업일 기준 약 1~2일이 소요됩니다.
Conversational Analytics API 리소스와 동일한 위치에 Cloud KMS 키링 및 키를 만듭니다. 자세한 내용은 키 만들기를 참고하세요.
제품별, 프로젝트별 서비스 계정 (P4SA)이라고도 하는 Google 관리 서비스 에이전트를 아직 없는 경우 만듭니다. 이러한 서비스 에이전트는 CMEK로 Conversational Analytics API 리소스를 보호하는 데 관련된 서비스가 Cloud KMS 키에 액세스할 수 있도록 하는 데 필요합니다.

다음 gcloud 명령어를 실행하여 서비스 에이전트를 만듭니다.
```
gcloud beta services identity create --service=geminidataanalytics.googleapis.com --project PROJECT_ID
gcloud beta services identity create --service=cloudaicompanion.googleapis.com --project PROJECT_ID
```
PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.
Gemini 데이터 분석 서비스가 대화형 분석 API 데이터를 암호화하고 복호화하는 데 Cloud KMS 키를 사용할 수 있도록 이전 단계에서 만든 두 서비스 에이전트에 Identity and Access Management (IAM)의 Cloud KMS CryptoKey 암호화/복호화 (roles/cloudkms.cryptoKeyEncrypterDecrypter) 역할을 부여합니다.

Gemini 데이터 분석 서비스 에이전트에 권한을 부여합니다.
```
gcloud kms keys add-iam-policy-binding KEY_NAME \
  --location KEY_LOCATION \
  --keyring KEY_RING_NAME \
  --member
serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project KMS_PROJECT_ID
```
Gemini for Google Cloud API 서비스 에이전트에 권한을 부여합니다.
```
gcloud kms keys add-iam-policy-binding KEY_NAME \
  --location KEY_LOCATION \
  --keyring KEY_RING_NAME \
  --member
serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudaicompanion.iam.gserviceaccount.com \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project KMS_PROJECT_ID
```
이전 코드 예시에서 샘플 값을 다음과 같이 바꿉니다.
- KEY_NAME: Cloud KMS 키의 이름입니다.
- KEY_LOCATION: 키링의 리전 (예: us-east4)
- KEY_RING_NAME: 키링의 이름입니다.
- PROJECT_NUMBER: API 리소스를 만들 Google Cloud 프로젝트 번호입니다.
- KMS_PROJECT_ID: 키가 생성된 프로젝트 ID입니다. API 리소스를 만드는 프로젝트와 동일할 수 있습니다.

CMEK로 리소스 보호

이 섹션에서는 리소스 생성 중에 REST API를 사용하여 kms_key 필드에 Cloud KMS 키를 지정하여 CMEK로 새 DataAgent 또는 Conversation 리소스를 보호하는 방법을 보여줍니다.

DataAgent 또는 Conversation 리소스를 만들 때만 CMEK를 사용 설정할 수 있습니다.

CMEK 키는 보호하는 리소스와 동일한 리전에 있어야 합니다. 자세한 내용은 제한사항을 참고하세요.

CMEK로 `DataAgent` 리소스 보호

CMEK로 새 DataAgent 리소스를 보호하려면 데이터 에이전트를 만들 때 kms_key 필드에 Cloud KMS 키를 지정하세요.

Python SDK

다음 예에서는 Python SDK로 DataAgent 리소스를 만들 때 Cloud KMS 키를 지정하는 방법을 보여줍니다. 완전한 create 요청의 예는 Python SDK를 사용하여 데이터 에이전트 빌드를 참고하세요.

# Define the KMS key.
billing_project = "BILLING_PROJECT_ID"
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Region of your key ring

if key_project == "":
  key_project = billing_project

kms_key_data_agent = f"projects/{key_project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}"

data_agent = geminidataanalytics.DataAgent()
data_agent.data_analytics_agent.published_context = published_context
data_agent.kms_key = kms_key_data_agent

이전 예시에서 값을 다음과 같이 바꿉니다.

BILLING_PROJECT_ID: 결제 프로젝트 ID
KEY_RING_NAME: Cloud KMS 키링의 이름입니다.
KEY_NAME: Cloud KMS 키의 이름입니다.
KMS_PROJECT_ID: 키가 생성된 프로젝트 ID입니다. 비워두면 billing_project이 사용됩니다.
LOCATION: 키링의 리전입니다.

HTTP

다음 예시에서는 HTTP 및 Python으로 DataAgent 리소스를 만들 때 요청 본문에 Cloud KMS 키를 지정하는 방법을 보여줍니다. 전체 create 요청의 예는 HTTP 및 Python을 사용하여 데이터 에이전트 빌드를 참고하세요.

data_agent_payload = {
      "name": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}",
      "description": "This is the description of data_agent_1.",
      # If using CMEK, include the kms_key field.
      "kms_key": f"projects/{key_project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}",
      "data_analytics_agent": {
          "published_context": {
              "datasource_references": looker_data_source,
              "system_instruction": system_instruction,
          }
      }
  }

이전 예시에서 값을 다음과 같이 바꿉니다.

KMS_PROJECT_ID: 키가 생성된 프로젝트 ID입니다.
LOCATION: 키링의 리전입니다.
KEY_RING_NAME: Cloud KMS 키링의 이름입니다.
KEY_NAME: Cloud KMS 키의 이름입니다.

CMEK로 `Conversation` 리소스 보호

CMEK로 새 Conversation 리소스를 보호하려면 대화를 만들 때 kms_key 필드에 Cloud KMS 키를 지정합니다.

Python SDK

다음 예에서는 Python SDK로 Conversation 리소스를 만들 때 Cloud KMS 키를 지정하는 방법을 보여줍니다. 완전한 create 요청의 예는 Python SDK를 사용하여 데이터 에이전트 빌드를 참고하세요.

# Define the KMS key.
billing_project = "BILLING_PROJECT_ID"
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Region of your key ring

if key_project == "":
  key_project = billing_project

kms_key_conversation = f"projects/{key_project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}"

conversation = geminidataanalytics.Conversation()
conversation.agents = [f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"]
conversation.kms_key = kms_key_conversation

이전 예시에서 값을 다음과 같이 바꿉니다.

BILLING_PROJECT_ID: 결제 프로젝트 ID
KEY_RING_NAME: Cloud KMS 키링의 이름입니다.
KEY_NAME: Cloud KMS 키의 이름입니다.
KMS_PROJECT_ID: 키가 생성된 프로젝트 ID입니다. 비워두면 billing_project이 사용됩니다.
LOCATION: 키링의 리전입니다.

HTTP

다음 예시에서는 HTTP 및 Python으로 Conversation 리소스를 만들 때 요청 본문에 Cloud KMS 키를 지정하는 방법을 보여줍니다. 전체 create 요청의 예는 HTTP 및 Python을 사용하여 데이터 에이전트 빌드를 참고하세요.

conversation_payload = {
    "agents": [
        f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
    ],
    "name": f"projects/{billing_project}/locations/{location}/conversations/{conversation_id}",
    # If using CMEK, include the kms_key field.
    "kms_key": f"projects/{key_project}/locations/{location}/keyRings/{key_ring_name}/cryptoKeys/{key_name}"
}

이전 예시에서 값을 다음과 같이 바꿉니다.

KMS_PROJECT_ID: 키가 생성된 프로젝트 ID입니다.
LOCATION: 키링의 리전입니다.
KEY_RING_NAME: Cloud KMS 키링의 이름입니다.
KEY_NAME: Cloud KMS 키의 이름입니다.

문제 해결

이 섹션에서는 Conversational Analytics API와 함께 CMEK를 사용할 때 발생하는 일반적인 문제와 중요한 고려사항을 다룹니다.

키 상태 변경

Conversational Analytics API 리소스를 보호하는 Cloud KMS 키 버전을 사용할 수 없게 되면 해당 키로 암호화된 데이터에 액세스할 수 없게 됩니다. 키를 사용할 수 없는 동안 보호된 데이터에 액세스하려고 하면(예: DataAgent 리소스의 컨텍스트를 읽거나 Conversation 기록에 액세스) 요청이 실패합니다. 반환되는 오류는 키를 사용할 수 없는 이유에 따라 다릅니다.

키 버전이 사용 중지되거나 폐기되면 일반적으로 FAILED_PRECONDITION 오류와 함께 작업이 실패합니다.
gcp-sa-geminidataanalytics 또는 gcp-sa-cloudaicompanion 서비스 에이전트에서 cloudkms.cryptoKeyEncrypterDecrypter IAM 역할이 취소되면 일반적으로 PERMISSION_DENIED 또는 NOT_FOUND 오류와 함께 작업이 실패합니다.

키를 사용할 수 없는 경우에도 콘텐츠 복호화가 필요하지 않은 작업(예: DataAgent 또는 Conversation 리소스 삭제)은 계속 실행할 수 있습니다.

암호화된 데이터에 대한 액세스 권한을 복원하려면 시작하기 전에 설명된 대로 키를 다시 사용 설정하고 서비스 에이전트에 필요한 IAM 권한이 있는지 확인합니다.

Cloud KMS 할당량 및 Conversational Analytics API

Conversational Analytics API에서 CMEK를 사용하면 프로젝트에서 Cloud KMS 암호화 요청 할당량을 사용할 수 있습니다. 예를 들어 CMEK로 보호되는 DataAgent 리소스를 읽거나 Conversation 기록에 액세스하려면 Cloud KMS가 데이터를 복호화해야 합니다.

CMEK 키를 사용한 암호화 및 복호화 작업은 다음과 같은 방식으로 Cloud KMS 할당량에 영향을 미칩니다.

Cloud KMS에서 생성된 소프트웨어 CMEK 키의 경우 Cloud KMS 할당량이 사용되지 않습니다.
하드웨어 CMEK 키(Cloud HSM 키라고도 함)의 경우 키가 포함된 프로젝트의 Cloud HSM 할당량에 암호화 및 복호화 작업이 집계됩니다.
외부 CMEK 키(Cloud EKM 키라고도 함)의 경우 키가 포함된 프로젝트의 Cloud EKM 할당량에 암호화 및 복호화 작업이 집계됩니다.

자세한 내용은 Cloud KMS 할당량을 참조하세요.

다음 단계

Conversational Analytics API를 사용 설정하는 방법을 알아보세요.
Conversational Analytics API로 데이터 소스를 인증하고 연결하는 방법을 알아보세요.
Python SDK를 사용하여 데이터 에이전트를 빌드하는 방법을 알아보세요.
HTTP 및 Python을 사용하여 데이터 에이전트를 빌드하는 방법을 알아봅니다.
Cloud KMS에 대해 자세히 알아보기
CMEK 조직 정책에 대해 알아봅니다.

고객 관리 암호화 키(CMEK) 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

Conversational Analytics API 리소스의 CMEK

CMEK로 보호되는 대상

제한사항

시작하기 전에

콘솔

gcloud

CMEK로 리소스 보호

CMEK로 DataAgent 리소스 보호

Python SDK

HTTP

CMEK로 Conversation 리소스 보호

Python SDK

HTTP

문제 해결

키 상태 변경

Cloud KMS 할당량 및 Conversational Analytics API

다음 단계

고객 관리 암호화 키(CMEK)

CMEK로 `DataAgent` 리소스 보호

CMEK로 `Conversation` 리소스 보호