使用 Azure 密钥保管库为现有 Azure Cosmos DB 帐户配置客户管理的密钥

适用对象： NoSQL MongoDB Gremlin 表

现在，在创建新的 Azure Cosmos DB 帐户时，使用客户管理的密钥为静态数据启用第二层加密已正式发布一段时间。 作为自然的下一步，我们现在能够在现有 Azure Cosmos DB 帐户上启用 CMK。

此功能无需将数据迁移到新帐户即可启用 CMK。 它有助于改善客户的安全性和合规性状况。

启用 CMK 会启动后台异步过程来加密帐户中的所有现有数据，而新的传入数据会在持久化之前加密。 无需等待异步操作成功。 启用过程将使用未使用的/备用 RU，因此不会影响读/写工作负载。 在帐户加密后，可以参考此链接来进行容量规划。

在现有帐户上启用 CMK 入门

先决条件

在为新帐户配置客户管理的密钥时所需的所有先决条件步骤适用于在现有帐户上启用 CMK。 请参考此处的步骤

若要验证你的帐户是否合规，可以使用提供的、在此处托管的控制台应用程序扫描该帐户。 无论选择哪个 API，都请确保使用“sqlEndpoint”帐户属性中的终结点。

如果你希望在迁移过程中为此帐户禁用服务器端验证，请联系支持人员。

在现有帐户上启用 CMK 的步骤

要在现有帐户上启用 CMK，请使用 ARM 模板在 keyVaultKeyUri 属性中设置密钥保管库密钥标识符来更新帐户 - 就像在新帐户上启用 CMK 一样。 可以通过发出具有以下有效负载的 PATCH 调用来完成此步骤：

    {
        "properties": {
        "keyVaultKeyUri": "<key-vault-key-uri>"
        }
    }

用于启用 CMK 的此 CLI 命令的输出将等待数据加密完成。

    az cosmosdb update --name "testaccount" --resource-group "testrg" --key-uri "https://keyvaultname.vault.azure.cn/keys/key1"

使用连续备份或分析存储帐户在现有 Azure Cosmos DB 帐户上启用 CMK 的步骤

要在启用了连续备份和时间点还原的现有帐户上启用 CMK，我们需要执行一些额外的步骤。 按照步骤 1 到步骤 5 操作，然后按照说明在现有帐户上启用 CMK。

1. 为 Cosmos 帐户配置托管标识 使用 Microsoft Entra ID 为 Azure Cosmos DB 帐户配置托管标识

2. 更新 cosmos 帐户，以将默认标识设置为指向上一步中添加的托管标识

   对于系统托管标识：

   az cosmosdb update--resource-group $resourceGroupName --name $accountName --default-identity "SystemAssignedIdentity"
   

   对于用户管理的标识：

   az cosmosdb update -n $sourceAccountName -g $resourceGroupName --default-identity "UserAssignedIdentity=/subscriptions/00000000-0000-0000-0000-00000000/resourcegroups/MyRG/providers/Microsoft.ManagedIdentity/userAssignedIdentities/MyID"
   

3. 按照此处文档中所述配置 Keyvault

4. 在密钥保管库中为上一步中设置的默认标识添加访问策略

5. 更新 cosmos 帐户以设置 keyvault URI，此更新会触发在帐户上启用 CMK 的操作

   az cosmosdb update --name $accountName --resource-group $resourceGroupName --key-uri $keyVaultKeyURI  
   

已知限制

• 我们不支持在现有的 Azure Cosmos DB for Apache Cassandra 帐户上启用 CMK。
• 启用 CMK 仅在 Cosmos DB 帐户级别可用，在集合中则不可用。
• 我们不支持在已启用具体化视图以及所有版本和删除更改源模式的现有帐户上启用 CMK。
• 在启用 CMK 之前，请确保帐户中不得包含大于 990 字节的大型 ID 的文档。 否则，由于加密后的最大支持限制为 1024 字节，你将收到错误。
• 在加密现有数据期间，将会阻止控制平面操作（如“添加区域”）。 以下操作不会受到阻止，并且可以在加密完成后立即使用。

监视生成的加密的进度

在现有帐户上启用 CMK 是一种异步操作，可启动加密所有现有数据的后台任务。 因此，启用 CMK 的 REST API 请求在其响应中提供了“Azure-AsyncOperation”URL。 使用 GET 请求轮询此 URL 将返回整个操作的状态，这最终会成功。 本文对此机制进行了全面介绍。

可以继续使用 Cosmos DB 帐户，并且可以继续写入数据，而无需等待异步操作成功。 用于启用 CMK 的 CLI 命令将等待数据加密完成。

若要允许现有 Cosmos DB 帐户使用 CMK，需要执行扫描，以确保该帐户没有“大 ID”。 “大 ID”是长度超过 990 个字符的文档 ID。 此扫描对于 CMK 迁移是必需的，由 Microsoft 自动执行。 在此过程中可能会出现错误。

错误: (InternalServerError) 为 CMK 迁移执行文档扫描时发生意外错误。 请重试该操作。

如果扫描过程使用的 RU 多于集合中预配的 RU，就会发生这种情况，并引发 429 错误。 此问题的解决方法是暂时性地大幅增加 RU。 或者，可以利用提供的、托管在此处的控制台应用程序来扫描其集合。

如有其他问题，请联系 Microsoft 支持部门。

常见问题解答

加密时间取决于哪些因素？

启用 CMK 是一种异步操作，取决于可用的足够未使用 RU。 建议在非高峰时段启用 CMK，并且如果适用，可以提前增加 RU 以加快加密速度。 它也是数据大小的直接函数。

是否需要为停机时间做好准备？

启用 CMK 会启动后台异步过程来加密所有数据。 无需等待异步操作成功。 Azure Cosmos DB 帐户可用于读取和写入，无需停机。

触发 CMK 后，是否可以提高 RU？

建议在触发 CMK 之前增加 RU。 触发 CMK 后，将会在加密完成之前阻止某些控制平面操作。 触发 CMK 后，此阻止操作可能会阻止用户增加 RU。

若要允许现有 Cosmos DB 帐户使用 CMK，Microsoft 必须自动执行大 ID 扫描，以解决前面列出的已知限制之一。 此过程还会消耗更多 RU，因此最好大幅增加 RU 以免出现错误 429。

在触发 CMK 后，是否可以采用某种方法还原加密或禁用加密？

触发使用 CMK 的数据加密过程后，将无法还原。

在现有帐户上使用 CMK 启用加密是否会对数据大小和读/写产生影响？

正如你所料，通过启用 CMK，数据大小和 RU 会略有增加，以适应额外的加密/解密处理。

是否应在启用 CMK 之前备份数据？

启用 CMK 不会造成任何数据丢失威胁。

作为定期备份的一部分进行的旧备份是否会加密？

不是。 旧的定期备份不会加密。 将对启用 CMK 后新生成的备份进行加密。

启用连续备份的现有帐户会有什么行为？

启用 CMK 后，还会为连续备份启用加密。 启用 CMK 后，所有未来还原的帐户都将启用 CMK。

如果在启用了 PITR 的帐户上启用了 CMK 并将帐户还原到禁用 CMK 的时间，会发生什么行为？

在这种情况下，由于以下原因，在还原的目标帐户上将会显式启用 CMK：

• 在帐户上启用 CMK 后，无法选择禁用 CMK。
• 如果定期备份，此行为符合还原已启用 CMK 的帐户的当前设计

当用户在 CMK 迁移正在进行时撤消密钥时会发生什么情况？

触发 CMK 加密后，将检查密钥的状态。 如果 Azure 密钥保管库中的密钥状态良好，则会启动加密并完成该过程，而无需进一步检查。 即使撤销了密钥，或者 Azure 密钥保管库被删除或不可用，加密过程也会成功。

能否在现有生产帐户上启用 CMK 加密？

是的。 彻底完成先决条件部分。 建议首先在非生产帐户中测试所有方案，感到满意后，可以考虑在生产帐户中测试。

后续步骤

• 详细了解 Azure Cosmos DB 中的数据加密。
• 可以选择使用自己的密钥来添加另一层加密，若要了解详细信息，请参阅客户托管的密钥一文。
• 有关 Azure Cosmos DB 安全性的概述以及最新改进，请参阅 Azure Cosmos DB 数据库安全性。
• 有关 Microsoft 认证的详细信息，请参阅 Azure 信任中心。