为沙盒配置客户管理的加密密钥 (CMEK)

使用您拥有和控制的 Cloud Key Management Service 密钥加密沙盒的静态数据。

概览

默认情况下， Google Cloud 会使用 Google-owned and Google-managed encryption keys对静态数据进行加密。借助客户管理的加密密钥 (CMEK)，您可以创建和管理 Cloud KMS 加密密钥，以便审核其使用情况、轮替密钥，以及停用或销毁密钥，使受保护的数据无法读取。

Gemini Enterprise Agent Platform 沙盒会在隔离环境中运行智能体的代码、浏览器或自定义容器。该环境会将客户内容写入磁盘，并可将其检查点保存到快照中。当您在沙盒的父级 Gemini Enterprise Agent Platform 实例上启用 CMEK 时，CMEK 会保护这些快照。

您只能在创建 Gemini Enterprise Agent Platform 实例时为 Gemini Enterprise Agent Platform 沙盒配置 CMEK。CMEK 密钥可保护 Gemini Enterprise Agent Platform 实例及其子资源，包括沙盒环境、模板和快照。

CMEK 为沙盒加密的内容

在父级 Gemini Enterprise Agent Platform 实例上启用 CMEK 后，系统会使用您的密钥对沙盒的静态表面进行加密：

  • GKE 节点启动磁盘/根文件系统：会话在运行时写入的文件以及分页到磁盘的内存中状态（节点启动磁盘 CMEK）。
  • 快照 Cloud Storage 存储桶：沙盒的磁盘和内存检查点（快照）（存储桶默认加密）。

资源元数据（名称、标签、状态、连接信息）、环境变量和服务账号电子邮件地址不会使用 CMEK 密钥进行加密。

如需加密自定义容器映像，请在您自己的 Artifact Registry 仓库中设置 CMEK。

限制和注意事项

  • Gemini Enterprise Agent Platform 上的 CMEK 仅支持单区域密钥。不支持多区域、双区域和全球密钥。
  • 创建 Gemini Enterprise Agent Platform 实例后，密钥不可变。如需使用其他密钥，您需要创建新的 Gemini Enterprise Agent Platform 实例。支持轮替到同一密钥的新版本，并会自动应用。
  • 如果您停用或销毁密钥版本，或者撤消 Encrypter/Decrypter 角色，则无法预配或恢复沙盒，并且快照写入会失败。恢复密钥访问权限，以恢复沙盒资源。

准备工作

  • 拥有或创建 Cloud KMS 密钥环和密钥。最佳实践是将密钥保存在与 Gemini Enterprise Agent Platform 工作负载不同的项目中，并由不同的管理员管理。
  • 确认您拥有创建和管理密钥 (roles/cloudkms.admin) 以及创建 Gemini Enterprise Agent Platform 实例的角色。

  • 创建 Agent Runtime 服务代理（如果您尚未创建）：

    # Create the service agent if needed
gcloud beta services identity create \
    --service=aiplatform.googleapis.com \
    --project=PROJECT_ID

创建 Cloud KMS 密钥

在 Gemini Enterprise Agent Platform 实例所在的区域中创建单区域密钥：

# Key ring (once per region)
gcloud kms keyrings create sandbox-keyring \
    --location=REGION

# Key
gcloud kms keys create sandbox-key \
    --location=REGION \
    --keyring=sandbox-keyring \
    --purpose=encryption

替换以下内容：

  • REGION：Gemini Enterprise Agent Platform 实例的 Google Cloud 区域（例如 us-central1）。

向 Agent Platform 服务代理授予对密钥的访问权限

向 Agent Runtime 服务代理授予该密钥的 Cloud KMS CryptoKey Encrypter/Decrypter 角色 (roles/cloudkms.cryptoKeyEncrypterDecrypter)：

# Grant Encrypter/Decrypter on the key
gcloud kms keys add-iam-policy-binding sandbox-key \
    --location=REGION \
    --keyring=sandbox-keyring \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com" \
    --role="roles/cloudkms.cryptoKeyEncrypterDecrypter"

替换以下内容：

  • PROJECT_NUMBER：您的 Google Cloud 项目编号。

在 Agent Platform 实例上启用 CMEK

在创建 Gemini Enterprise Agent Platform 实例时设置 encryption_spec.kms_key_name。您在其中创建的每个沙盒模板和沙盒都会继承此密钥。

Python SDK

import vertexai

client = vertexai.Client(project="PROJECT_ID", location="REGION",
                        http_options={"api_version": "v1beta1"})
agent_instance = client.agent_engines.create(
    config={
        "encryption_spec": {
            "kms_key_name":
                "projects/PROJECT_ID/locations/REGION/keyRings/sandbox-keyring/cryptoKeys/sandbox-key"
        }
    },
)

REST

使用 REST API，在创建时将 reasoningEngines.encryptionSpec.kmsKeyName 设置为相同的值：

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines \
  -d '{
    "display_name": "cmek-protected-engine",
    "encryption_spec": {
      "kms_key_name": "projects/PROJECT_ID/locations/REGION/keyRings/sandbox-keyring/cryptoKeys/sandbox-key"
    }
  }'

创建沙盒并验证 CMEK 配置

  1. 在受 CMEK 保护的 Gemini Enterprise Agent Platform 实例下创建沙盒模板和沙盒。
  2. 通过获取实例详细信息，确认 Gemini Enterprise Agent Platform 实例在 encryption_spec.kms_key_name 中报告了您的密钥。
  3. （可选）查看 Cloud KMS 审核日志，确认在沙盒启动和快照写入时是否执行了加密和解密操作。

后续步骤