客户管理的加密密钥

本页介绍了如何使用您自己的加密密钥来保护位于美国和欧盟多个区域的数据存储空间。

默认情况下，Vertex AI Agent Builder 会对以静态方式存储的内容进行加密。Vertex AI Agent Builder 会为您处理和管理这项默认加密作业，您无需进行任何其他操作。

不过，如果您对保护数据的密钥有特定的合规性或监管要求，则可以使用客户管理的加密密钥 (CMEK) 来保护资源。在这种情况下，您将使用 Cloud KMS 密钥，并按照本页中的步骤操作。该密钥与特定位置相关联：美国多区域或欧盟多区域。

Cloud KMS 密钥用于加密和解密数据存储区和应用中的数据。如需了解 Cloud KMS 的一般信息，请参阅 Cloud Key Management Service 文档。

Vertex AI Agent Builder 中的 Cloud KMS 限制

Vertex AI Agent Builder 中的 CMEK (Cloud KMS) 密钥存在以下限制：

  • 已应用于数据存储区的密钥无法更改。

  • 如果您有 CMEK 组织政策，则必须使用 API（而非 Google Cloud 控制台）创建新的数据存储区。如果您启用了 CMEK 组织政策，则无法使用 Google Cloud 控制台创建新的数据存储空间。

  • 密钥一经注册便无法取消注册或从数据存储区中移除。

  • 您必须使用美国或欧盟的多区域数据存储空间和应用（而非全球性数据存储空间和应用）。 如需详细了解多区域和数据驻留，包括与使用非全球位置相关的限制，请参阅 Vertex AI Search 位置或 Vertex AI 代理位置。

  • 如果您需要为项目注册多个密钥，请与您的 Google 客户支持团队联系，请求增加 CMEK 配置的配额，并说明您需要多个密钥的原因。

  • 将外部密钥管理器 (EKM) 或硬件安全模块 (HSM) 与 CMEK 搭配使用已进入 GA 阶段，并已列入许可名单。如需将 EKM 或 HSM 与 CMEK 搭配使用，请与您的 Google 客户支持团队联系。

    使用 CMEK 的 EKM 或 HSM 存在以下限制：

    • 用于加密和解密调用的 EKM 和 HSM 配额应至少有 1,000 QPM 的余量。如需了解如何查看配额，请参阅查看 Cloud KMS 配额。

    • 如果使用 EKM，则在任何超过 30 秒的时间范围内，密钥必须在 90% 的时间内可访问。如果在此时间段内无法访问该键，则可能会对索引编制和搜索新鲜度产生负面影响。

    • 如果存在结算问题、配额超出问题或持续超过 12 小时的不可访问问题，该服务会自动降低与 EKM 或 HSM 密钥关联的 CmekConfig。

  • 在将密钥注册到项目之前创建的数据存储区无法受该密钥保护。

  • 对于 Vertex AI Search，必须使用企业版。如需了解企业版，请参阅高级功能简介。

  • 您无法为受 CMEK 密钥保护的数据存储区调整搜索模型。

  • 医疗保健搜索数据存储区符合 CMEK 要求。不过，其他第三方连接器数据存储区和 BigQuery 定期连接器不符合 CMEK 要求。如需了解有关医疗保健数据存储区的一般信息，请参阅创建医疗保健搜索数据存储区。如需了解第三方连接器的一般信息，请参阅连接第三方数据源。

  • 推荐应用不支持密钥轮替。 如果您停用或销毁用于保护与推荐应用关联的数据存储区的密钥版本，则推荐应用将停止运行。

  • 密钥轮替与分析不兼容。如果您轮替数据存储区的密钥，则使用该数据存储区的应用将不再显示分析数据。

  • CMEK 密钥不适用于以下 RAG API：检查依据、排名和有依据的生成。

准备工作

请确保您满足以下前提条件：

  • 轮替周期设置为永不（手动轮替）的对称 Cloud KMS 密钥。请参阅 Cloud KMS 文档中的创建密钥环和创建密钥。

  • 已向 Discovery Engine 服务代理授予密钥的 CryptoKey Encrypter/Decrypter IAM 角色 (roles/cloudkms.cryptoKeyEncrypterDecrypter)。如需了解如何向服务代理添加角色的一般说明，请参阅授予或撤消单个角色。

  • 已向 Cloud Storage 服务代理授予密钥上的 CryptoKey Encrypter/Decrypter IAM 角色 (roles/cloudkms.cryptoKeyEncrypterDecrypter)。如果未授予此角色，则受 CMEK 保护的数据存储区的数据导入将会失败，因为 Discovery Engine 无法创建导入所需的受 CMEK 保护的临时存储桶和目录。

  • 请先完成本页中的密钥注册说明，然后再创建要由密钥管理的任何数据存储空间或应用。

  • 应用已启用企业版功能。请参阅启用或停用企业版。

注册 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. 大约一周后，停用旧密钥版本，并确保一切照常运行。

    4. 在以后的某个时间，当您确定停用旧密钥版本不会造成任何问题时，可以销毁旧密钥版本。

如果密钥已停用或撤消

如果密钥被停用或密钥的权限被撤消，数据存储区会在 15 分钟内停止提取数据并停止传送数据。不过，重新启用密钥或恢复权限需要很长时间。数据存储区最长可能需要 24 小时才能恢复提供数据。

因此，除非必要，否则请勿停用密钥。在数据存储区中停用和启用键是一项耗时的操作。例如，如果反复将密钥在停用和启用之间切换，则数据存储区将需要很长时间才能达到受保护状态。停用密钥并在停用后立即重新启用密钥可能会导致数天的数据库停机，因为系统会先从数据存储区停用密钥，然后再重新启用密钥。