Настройка управляемых клиентом ключей для существующей учетной записи Azure Cosmos DB с помощью Azure Key Vault

Статья
2025-04-11

Область применения: NoSQL Mongodb Гремлин Таблица

Включение второго уровня шифрования для неактивных данных с помощью ключей , управляемых клиентом, при создании новой учетной записи Azure Cosmos DB уже некоторое время доступно. В качестве естественного следующего шага теперь у нас есть возможность включить CMK в существующих учетных записях Azure Cosmos DB.

Эта функция устраняет необходимость миграции данных в новую учетную запись для включения CMK. Это помогает улучшить уровень безопасности и соответствия требованиям клиентов.

Включение CMK запускает фоновый асинхронный процесс для шифрования всех существующих данных в учетной записи, а новые входящие данные шифруются перед сохранением. Нет необходимости ждать успешной асинхронной операции. Процесс включения потребляет неиспользуемые или запасные ЕЗ, чтобы не влиять на рабочие нагрузки чтения и записи. Эту ссылку можно использовать для планирования емкости после шифрования учетной записи.

Начните с того, что включите CMK в ваши текущие учетные записи

Внимание

Тщательно изучите раздел предварительных требований. Эти предварительные требования являются важными соображениями.

Предварительные условия

Все необходимые действия, необходимые при настройке управляемых клиентом ключей для новых учетных записей, применимы для включения CMK в существующей учетной записи. Ознакомьтесь с инструкциями здесь

Примечание.

Важно отметить, что включение шифрования в учетной записи Azure Cosmos DB добавляет небольшую нагрузку на идентификатор документа, что ограничивает максимальный размер идентификатора документа до 990 байт вместо 1024 байт. Если у вашей учетной записи есть документы с идентификаторами размером более 990 байт, процесс шифрования завершается сбоем, пока эти документы не будут удалены.

Чтобы проверить соответствие учетной записи, можно использовать предоставленное консольное приложение , размещенное здесь , для проверки учетной записи. Убедитесь, что вы используете конечную точку доступа из свойства учетной записи «sqlEndpoint», независимо от выбранного API.

Если вы хотите отключить проверку на стороне сервера во время миграции, обратитесь в службу поддержки.

Действия по включению CMK в существующей учетной записи

Чтобы включить CMK в существующей учетной записи, обновите учетную запись с помощью шаблона ARM, задав идентификатор ключа Key Vault в свойстве keyVaultKeyUri, как и при включении CMK в новой учетной записи. Этот шаг можно выполнить, отправив запрос PATCH с следующим содержимым:

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

Вывод этой команды CLI, включающей CMK, ожидает завершения процесса шифрования данных.

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

Действия по включению CMK в вашу существующую учетную запись Azure Cosmos DB с функцией непрерывного резервного копирования или аналитическим хранилищем.

Чтобы включить CMK в существующей учетной записи с поддержкой непрерывного резервного копирования и восстановления на определенный момент времени, необходимо выполнить некоторые дополнительные действия. Выполните шаги с 1 по 5, а затем следуйте инструкциям, чтобы включить CMK в уже существующей учетной записи.

Настройка управляемого удостоверения для вашей учетной записи Azure Cosmos DB Настройка управляемых удостоверений с помощью Microsoft Entra ID для вашей учетной записи Azure Cosmos DB
Обновите учетную запись 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"
```
Настройте Keyvault, как указано в документации здесь
Добавьте политику доступа в хранилище ключей для удостоверения по умолчанию, заданного на предыдущем шаге.
Обновите учетную запись Cosmos, чтобы задать URI для Key Vault, это обновление запускает включение CMK (управляемый клиентом ключ) в учетной записи.
```
az cosmosdb update --name $accountName --resource-group $resourceGroupName --key-uri $keyVaultKeyURI  
```

Известные ограничения

Поддержка включения CMK для существующих учетных записей службы Apache Cassandra в Azure Cosmos DB не осуществляется.
Включение CMK доступно только на уровне учетной записи Cosmos DB, а не в коллекциях.
Включение CMK в существующих учетных записях, для которых включены материализованные представления и все версии и удаление режима канала изменений, не поддерживается.
Убедитесь, что у учетной записи не должно быть документов с большими идентификаторами, превышающими 990 байт, прежде чем включить CMK. В противном случае вы получите ошибку из-за максимального поддерживаемого ограничения в 1 024 байта после шифрования.
Во время шифрования существующих данных действия уровня управления, такие как добавление региона, блокируются. Эти действия разблокируются и могут использоваться сразу после завершения шифрования.

Мониторинг хода выполнения результирующего шифрования

Включение CMK в существующей учетной записи — это асинхронная операция, которая запускает фоновую задачу, которая шифрует все существующие данные. Таким образом, запрос REST API для включения CMK предоставляет в ответе URL-адрес Azure-AsyncOperation. Опрос данного URL-адреса с помощью запросов GET возвращает статус общей операции, которая в конечном итоге завершается успешно. Этот механизм полностью описан в этой статье.

Учетная запись Cosmos DB может продолжать использоваться, и данные могут продолжать записываться без ожидания асинхронной операции. Команда CLI для включения CMK ожидает завершения шифрования данных.

Чтобы разрешить существующей учетной записи Cosmos DB использовать CMK, необходимо выполнить проверку, чтобы убедиться в отсутствии «Больших идентификаторов». «Большой идентификатор» — это идентификатор документа, длина которого превышает 990 символов. Эта проверка является обязательной для миграции CMK, и она выполняется корпорацией Майкрософт автоматически. Во время этого процесса может возникнуть ошибка.

ERROR: (InternalServerError) Непредвиденная ошибка при сканировании документов для миграции CMK. Повторите операцию.

Эта ошибка возникает, когда процесс сканирования использует больше единиц запросов, чем те, которые подготовлены в коллекции, вызывая ошибку 429. Решение этой проблемы заключается в том, чтобы временно значительно увеличить их RUs. Кроме того, вы можете использовать предоставленное консольное приложение , размещенное здесь , для проверки их коллекций.

Примечание.

Если вы хотите отключить проверку на стороне сервера во время миграции, обратитесь в службу поддержки. Отключение проверки рекомендуется только в том случае, если вы уверены, что нет больших ID. Если во время шифрования обнаружен Large ID, процесс останавливается до тех пор, пока документ Large ID не будет обработан.

Если у вас есть дополнительные вопросы, обратитесь к служба поддержки Майкрософт.

Вопросы и ответы

Каковы факторы, от которых зависит время шифрования?

Включение CMK является асинхронной операцией и зависит от наличия достаточного количества неиспользуемых RUs. Мы рекомендуем включить CMK в непиковые часы и при необходимости заранее увеличить количество ЕЗ для ускорения шифрования. Это также прямая функция размера данных.

Нужно ли нам подготовиться к простою?

Включение CMK запускает фоновый асинхронный процесс для шифрования всех данных. Нет необходимости ждать успешной асинхронной операции. Учетная запись Azure Cosmos DB доступна для операций чтения и записи и не требует простоя.

Можете ли вы увеличить RUs после активации CMK?

Рекомендуем увеличить количество RUs перед активацией CMK. После активации CMK некоторые операции плоскости управления блокируются до завершения шифрования. Этот блок может запретить пользователю увеличивать количество запросов RUs после активации CMK.

Для того чтобы существующая учетная запись Cosmos DB могла использовать CMK, Майкрософт автоматически проводит обязательное сканирование большого идентификатора, чтобы устранить одно из известных ограничений, перечисленных ранее. Этот процесс также потребляет дополнительные RUs, и хорошей идеей будет значительно увеличить количество RUs, чтобы избежать ошибки 429.

Можно ли отменить шифрование или отключить шифрование после активации CMK?

После активации процесса шифрования данных с помощью CMK его нельзя отменить.

Включение шифрования с помощью CMK в существующей учетной записи влияет на размер данных и чтение и запись?

Как и следовало ожидать, включение CMK приводит к незначительному увеличению размера данных и RUs для поддержки дополнительной обработки шифрования и расшифровки.

Следует ли создавать резервные копии данных перед включением CMK?

Включение CMK не представляет никакой угрозы потери данных.

Старые резервные копии, выполненные в рамках периодического резервного копирования, зашифрованы?

Нет Старые периодические резервные копии не шифруются. Только что созданные резервные копии после включения CMK шифруются.

Что такое поведение существующих учетных записей, которые включены для непрерывного резервного копирования?

При включении CMK шифрование также включается для непрерывных резервных копий. После включения поддержки CMK все восстановленные учетные записи в дальнейшем будут с поддержкой CMK.

Что такое поведение, если CMK включена в учетной записи с поддержкой PITR, и мы восстанавливаем учетную запись до момента отключения CMK?

В этом случае CMK явно включен в восстановленной целевой учетной записи по следующим причинам:

После включения CMK в учетной записи невозможно отключить CMK.
Это поведение соответствует текущей структуре восстановления учетной записи с поддержкой CMK с периодической резервной копией.

Что происходит, когда пользователь отменяет ключ во время миграции CMK?

Состояние ключа проверяется при активации шифрования CMK. Если ключ в хранилище ключей Azure находится в хорошем положении, шифрование запускается и процесс завершается без дополнительной проверки. Даже если ключ отозван или хранилище ключей Azure удаляется или недоступно, процесс шифрования завершается успешно.

Можно ли включить шифрование CMK в существующей рабочей учетной записи?

Да. Тщательно ознакомьтесь с разделом предварительных требований. Рекомендуется сначала протестировать все сценарии на непроизводственных учетных записях, а затем, когда вы почувствуете уверенность, можно рассматривать использование рабочих учетных записей.

Как перенести учетную запись Azure Cosmos DB в другой клиент?

Если для вашей учетной записи Cosmos DB включены ключи, управляемые клиентом, вы можете переносить учетную запись только в том случае, если она является меж-арендаторской учетной записью с управляемыми клиентом ключами. Дополнительные сведения см. в руководстве по настройке клиентских ключей управления для разных тенантов в учетной записи Azure Cosmos DB с помощью Azure Key Vault.

Предупреждение

После миграции важно сохранить учетную запись Azure Cosmos DB и Azure Key Vault в отдельных арендаторах, чтобы сохранить исходную связь между арендаторами. Убедитесь, что ключ Key Vault остается на месте до завершения миграции учетной записи Cosmos DB.

Следующие шаги

Ознакомьтесь с дополнительными сведениями о шифровании данных в Azure Cosmos DB.
Подробные инструкции см. в статье о ключах, управляемых клиентом , если вы решили добавить второй уровень шифрования с помощью собственного ключа.
Изучите сертификаты Майкрософт в Центре управления безопасностью Azure.