客户管理的加密密钥

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

默认情况下，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 搭配使用 是正式版且已列入许可名单。如需将 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 文档中的创建密钥环和创建密钥。

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

  • CryptoKey Encrypter/Decrypter IAM 角色 (roles/cloudkms.cryptoKeyEncrypterDecrypter) 已授予 Cloud Storage 服务代理。如果未授予此角色，则数据导入 则对于受 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 密钥。

  2. 请参阅管理密钥部分的说明 Cloud KMS 指南，了解如何执行以下操作：

    1. 创建新的密钥版本，启用该版本，并将其设为主要版本。

    2. 将旧密钥版本保持启用状态。

    3. 大约一周后，停用旧密钥版本，并确保一切照常运行。

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

如果密钥被停用或撤消

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

因此，除非必要，否则请勿停用密钥。在数据存储区中停用和启用键是一项耗时操作。例如，反复切换 一个键位于“已停用”和“已启用”之间 表示启用键需要很长时间 达到受保护状态。停用密钥和 之后立即重新启用可能导致停机数天 因为首先在数据存储区中停用该键，随后又停用该键 。