客户管理的加密密钥

本页介绍了如何使用自己的加密密钥保护您的数据 。

默认情况下，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) 密钥存在以下限制：

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

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

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

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

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

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

• 你无法调整用于 由 CMEK 密钥保护。

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

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

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

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

准备工作

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

• 与您的 Google 客户代表联系 请求加入许可名单，以便由客户管理 Vertex AI Agent Builder 中的加密密钥。

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

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

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

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

• 已为应用启用企业版功能。请参阅 Turn 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：包含 键。项目编号无效。
   • 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 小时才能恢复提供数据。

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