고객 관리 암호화 키

이 페이지에서는 자체 암호화 키를 사용하여 미국 및 EU 멀티 리전에 있는 데이터 스토어를 보호하는 방법을 설명합니다.

기본적으로 Vertex AI Agent Builder는 저장된 콘텐츠를 암호화합니다. Vertex AI Agent Builder는 개발자의 추가 작업 없이 이 기본 암호화를 자동으로 처리하고 관리합니다.

하지만 데이터를 보호하는 키와 관련된 특정 규정 준수나 규제 기관 요구사항이 있으면 고객 관리 암호화 키(CMEK)를 사용하여 리소스를 보호하면 됩니다. 이 경우 Cloud KMS 키를 사용하고 이 페이지의 절차를 따릅니다. 키는 특정 위치(미국 멀티 리전 또는 EU 멀티 리전)와 연결됩니다.

Cloud KMS 키는 데이터 스토어와 앱의 데이터를 암호화하고 복호화하는 데 사용됩니다. Cloud KMS에 대한 일반적인 정보는 Cloud Key Management Service 문서를 참조하세요.

Vertex AI Agent Builder의 Cloud KMS 제한사항

Vertex AI Agent Builder의 CMEK(Cloud KMS) 키에 다음 제한사항이 적용됩니다.

  • 이미 데이터 스토어에 적용된 키를 변경할 수 없습니다.

  • 키가 등록된 후에는 데이터 스토어에서 등록을 해제하거나 키를 삭제할 수 없습니다.

  • 전역 리전이 아닌 미국 또는 EU 멀티 리전 데이터 스토어와 앱을 사용해야 합니다. 전역 위치 이외 위치 사용과 관련된 제한사항을 포함한 멀티 리전과 데이터 상주에 대한 자세한 내용은 Vertex AI Search 위치 또는 Vertex AI Agents 위치를 참조하세요.

  • 프로젝트에 키를 두 개 이상 등록해야 하는 경우 Google 계정팀에 문의하여 CMEK 구성 할당량 증가를 요청하고 키가 두 개 이상 필요한 이유를 설명합니다.

  • 키가 프로젝트에 등록되기 전에 생성된 데이터 스토어는 키로 보호될 수 없습니다.

  • Vertex AI Search의 경우 Enterprise 버전이 필요합니다. Enterprise 버전에 대한 자세한 내용은 고급 기능 정보를 참조하세요.

  • CMEK 키로 보호되는 데이터 스토어의 검색 모델을 조정할 수 없습니다.

  • 의료 검색 데이터 스토어는 CMEK를 준수합니다. 그러나 다른 서드 파티 커넥터 데이터 저장소와 BigQuery 주기적 커넥터는 CMEK를 준수하지 않습니다. 의료 데이터 스토어에 대한 일반적인 내용은 의료 검색 데이터 스토어 만들기를 참조하세요. 서드 파티 커넥터에 대한 일반적인 내용은 서드 파티 데이터 소스 연결을 참조하세요.

  • 추천 앱에는 키 순환이 지원되지 않습니다. 추천 콘텐츠 앱과 연결된 데이터 스토어를 보호하는 키 버전을 사용 중지하거나 삭제하면 추천 콘텐츠 앱이 작동하지 않습니다.

  • 키 순환은 애널리틱스와 호환되지 않습니다. 데이터 스토어의 키를 순환하면 애널리틱스는 해당 데이터 스토어를 사용하는 앱에 더 이상 표시되지 않습니다.

  • check grounding, ranking, grounded generation RAG API에는 CMEK 키가 적용되지 않습니다.

시작하기 전에

다음 기본 요건이 충족되었는지 확인합니다.

  • Google 계정 담당자에게 문의하여 Vertex AI Agent Builder의 고객 관리 암호화 키 허용 목록에 추가해 달라고 요청합니다.

  • 순환 기간이 없음(수동 순환)으로 설정된 대칭 Cloud KMS 키입니다. Cloud KMS 문서의 키링 만들기 및 키 만들기를 참조하세요.

  • 키의 CryptoKey 암호화/복호화 IAM 역할(roles/cloudkms.cryptoKeyEncrypterDecrypter)이 검색 엔진 서비스 에이전트에 부여되었습니다. 역할을 서비스 에이전트에 추가하는 방법에 대한 일반적인 안내는 단일 역할 부여 또는 취소를 참조하세요.

  • 키의 CryptoKey 암호화/복호화 IAM 역할(roles/cloudkms.cryptoKeyEncrypterDecrypter)이 Cloud Storage 서비스 에이전트에 부여되었습니다. 이 역할이 부여되지 않으면 검색 엔진에서 가져오기에 필요한 CMEK로 보호되는 임시 버킷과 디렉터리를 만들 수 없으므로 CMEK로 보호되는 데이터 스토어에 데이터를 가져올 수 없습니다.

  • 이 페이지의 키 등록 안내를 완료할 때까지 키로 관리하려는 데이터 스토어나 앱을 만들지 마세요.

  • Enterprise 버전 기능이 앱에 사용 설정되어 있습니다. Enterprise 버전 사용 또는 사용 중지를 참조하세요.

Cloud KMS 키 등록

Vertex AI Agent Builder에 자체 관리 키를 등록하려면 다음 단계를 수행합니다.

  1. 등록하려는 Cloud KMS 키를 사용하여 UpdateCmekConfig 메서드를 호출합니다.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"kms_key":"projects/KMS_PROJECT_ID/locations/KMS_LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"}' \
"https://LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID?set_default=SET_DEFAULT"
    • KMS_PROJECT_ID: 키가 포함된 프로젝트의 ID입니다. 프로젝트 번호는 작동하지 않습니다.
    • KMS_LOCATION: KMS 키의 멀티 리전입니다(us 또는 europe).
    • KEY_RING: 키가 저장된 키링의 이름입니다.
    • KEY_NAME: 키 이름
    • PROJECT_ID: 데이터 스토어가 포함된 프로젝트의 ID입니다.
    • LOCATION: 데이터 스토어의 멀티 리전입니다(us 또는 eu).
    • CMEK_CONFIG_ID: CmekConfig 리소스 ID입니다.
    • SET_DEFAULT: 키를 멀티 리전에서 이후에 생성된 데이터 스토어의 기본 키로 사용하려면 true로 설정합니다.

    curl 호출 및 응답 예시는 다음과 같습니다. 

    $ curl -X PATCH
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json
-d '{"kms_key":"projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"}'
"https://us-discoveryengine.googleapis.com/v1alpha/projects/my-ai-app-project-123/locations/us/cmekConfigs/cmek-config-1?set_default=true"
 
{
 "name": "projects/my-ai-app-project-123/locations/us/operations/update-cmek-config-56789",
 "metadata": {
  "@type": "type.googleapis.com/google.cloud.discoveryengine.v1alpha.UpdateCmekConfigMetadata"
 }
}

  2. 선택사항: 메서드에서 반환된 name 값을 기록하고 장기 실행 작업에 대한 세부정보 가져오기의 안내에 따라 작업이 완료된 시점을 확인합니다.

    일반적으로 키를 등록하는 데 몇 분 정도 걸립니다.

작업이 완료되면 해당 멀티 리전의 새 데이터 스토어가 키로 보호됩니다. 데이터 스토어를 만드는 방법에 대한 일반적인 내용은 검색 데이터 스토어 만들기를 참조하세요.

Cloud KMS 키 보기

Vertex AI Agent Builder에 등록된 키를 보려면 다음 중 하나를 수행합니다.

  • CmekConfig 리소스 이름이 있으면 GetCmekConfig 메서드를 호출합니다.

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/cmekConfigs/CMEK_CONFIG_ID"
    • LOCATION: 데이터 스토어의 멀티 리전입니다(us 또는 eu).
    • PROJECT_ID: 데이터가 포함된 프로젝트의 ID입니다.
    • CMEK_CONFIG_ID: CmekConfig 리소스 ID입니다.

    curl 호출 및 응답 예시는 다음과 같습니다. 

    $ curl -X GET
-H "Authorization: Bearer $(gcloud auth print-access-token)"
"https://us-discoveryengine.googleapis.com/v1alpha/projects/my-ai-app-project-123/locations/us/cmekConfigs/cmek-config-1"
 
{
  "name": "projects/my-ai-app-project-123/locations/us/cmekConfigs/cmek-config-1",
  "kms_key": "projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
  "state": "ACTIVE"
  "is_default": true
}

  • CmekConfig 리소스 이름이 없으면 ListCmekConfigs 메서드를 호출합니다.

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/cmekConfigs"
    • LOCATION: 데이터 스토어의 멀티 리전입니다(us 또는 eu).
    • PROJECT_ID: 데이터가 포함된 프로젝트의 ID입니다.

    curl 호출 및 응답 예시는 다음과 같습니다. 

    $ curl -X GET
-H "Authorization: Bearer $(gcloud auth print-access-token)"
"https://us-discoveryengine.googleapis.com/v1alpha/projects/my-ai-app-project-123/locations/us/cmekConfigs"
 
{
  "cmek_configs": [
    {
      "name": "projects/my-ai-app-project-123/locations/us/cmekConfigs/cmek-config-1",
      "kms_key": "projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
      "state": "ACTIVE"
      "is_default": true
    }
    {
      "name": "projects/my-ai-app-project-123/locations/us/cmekConfigs/cmek-config-2",
      "kms_key": "projects/key-project-456/locations/us/keyRings/my-key-ring/cryptoKeys/my-key-2"
      "state": "ACTIVE"
    }
  ]
}

선택사항: 데이터 스토어가 키로 보호되는지 확인

키가 등록되기 전에 생성된 데이터 저장소는 키로 보호되지 않습니다. 특정 데이터 스토어가 키로 보호되는지 확인하려면 다음 단계를 수행합니다.

  1. 데이터 스토어에서 다음 curl 명령어를 실행합니다.

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
"https://LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/dataStores/DATA_STORE_ID"
    • LOCATION: 데이터 스토어의 멀티 리전입니다(us 또는 eu).
    • PROJECT_ID: 데이터 스토어가 포함된 프로젝트의 ID입니다.
    • DATA_STORE_ID: 데이터 스토어 ID입니다.

    curl 호출 예시는 다음과 같습니다. 

    curl -X GET
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
-H "x-goog-user-project: my-ai-app-project-123"
"https://us-discoveryengine.googleapis.com/v1alpha/projects/my-ai-app-project-123/locations/us/collections/default_collection/dataStores/my-data-store-1"

  2. 명령어의 출력을 검토합니다. cmekConfig 필드가 출력에 있고 kmsKey 필드에 등록한 키가 표시되면 데이터 스토어가 키로 보호됩니다.

    응답 예시는 다음과 같습니다.

    {
 "name": "projects/969795412903/locations/us/collections/default_collection/dataStores/my-data-store-1",
 "displayName": "my-data-store-1",
 "industryVertical": "GENERIC",
 "createTime": "2023-09-05T21:20:21.520552Z",
 "solutionTypes": [
   "SOLUTION_TYPE_SEARCH"
 ],
 "defaultSchemaId": "default_schema",
 "cmekConfig": {
   "name": "projects/969795412903/locations/us/collections/default_collection/dataStores/my-data-store-1/cmekConfigs/cmek-config-1",
   "kmsKey": "projects/my-ai-app-project-123/locations/us/keyRings/my-key-ring/cryptoKeys/my-key"
 }
}

키 순환

키를 순환하면 새 버전의 키가 생성되고 새 버전이 기본 버전으로 설정됩니다. 키의 원래 버전을 사용 설정한 상태로 잠시 두었다가 사용 중지합니다. 이렇게 하면 이전 키를 사용하고 있을 수 있는 장기 실행 작업이 완료될 수 있습니다.

다음 절차에서는 Vertex AI Agent Builder 데이터 스토어의 키를 순환하는 단계를 간략히 설명합니다. 키 순환 방법에 대한 일반적인 내용은 Cloud KMS 가이드의 키 순환을 참조하세요.

중요: 추천 앱이나 분석이 필요한 앱과 연결된 데이터 스토어의 키를 순환하지 마세요. Vertex AI Agent Builder의 Cloud KMS 제한사항을 참조하세요.

  1. 키를 다시 등록합니다. Cloud KMS 키 등록의 1단계를 반복하여 이 작업을 수행합니다.

  2. Cloud KMS 가이드의 키 관리 섹션에 있는 안내를 참조하여 다음을 수행합니다.

    1. 새 키 버전을 만들고 사용 설정하여 기본 키 버전으로 지정합니다.

    2. 이전 키 버전을 사용 설정한 상태로 둡니다.

    3. 1주일 정도 지난 후 이전 키 버전을 사용 중지하고 모든 사항이 이전과 같이 작동하는지 확인합니다.

    4. 나중에 이전 키 버전 사용 중지로 인한 문제가 발생하지 않았다고 확신하면 이전 키 버전을 삭제할 수 있습니다.

키가 사용 중지되거나 취소된 경우

키가 사용 중지되거나 키에 대한 권한이 취소되면 데이터 스토어는 데이터 수집을 중지하고 15분 이내에 데이터 제공을 중지합니다. 하지만 키를 다시 사용 설정하거나 권한을 복원하는 데 시간이 오래 걸립니다. 데이터 스토어에서 데이터 제공을 재개하는 데 최대 24시간이 걸릴 수 있습니다.

따라서 필요한 경우가 아니라면 키를 사용 중지하지 마세요. 데이터 스토어에서 키를 사용 중지 및 사용 설정하는 작업은 시간이 오래 걸립니다. 예를 들어 키를 반복적으로 사용 중지하고 사용 설정하면 데이터 스토어가 보호되는 데 시간이 오래 걸립니다. 키를 사용 중지한 후 즉시 다시 사용 설정하면 키가 먼저 데이터 스토어에서 사용 중지된 후 다시 사용 설정되므로 며칠 동안 다운타임이 발생할 수 있습니다.