Доверия содержимому в реестре контейнеров Azure

  • Статья

Реестр контейнеров Azure реализует модель доверия к содержимому Docker, обеспечивая отправку и извлечение подписанных образов. Эта статья поможет приступить к реализации модели доверия к содержимому в ваших реестрах контейнеров.

Примечание.

Доверие к содержимому — это функция уровня служб "Премиум" в службе "Реестр контейнеров Azure".

Ограничения

  • Маркер с разрешениями на область репозитория в настоящее время не поддерживает отправку и извлечение подписанных образов docker.

Как работает функция доверия к содержимому

Для любой распределенной системы, созданной с учетом требований безопасности, важно проверить как источник, так и целостность данных, поступающих в эту систему. Получателям данных нужна возможность проверить издателя (источник) данных, а также убедиться в том, что они не были изменены после публикации (целостность).

Функция доверия к содержимому позволяет издателю подписывать образы, которые отправляются в реестр. Получатели образов (люди или системы, извлекающие эти образы из реестра) могут настроить свои клиенты для извлечения только подписанных образов. Когда получатель извлекает подписанный образ, Docker-клиент проверяет его целостность. Таким образом получателям гарантируется, что подписанные образы в вашем реестре были опубликованы именно вами и не были изменены после публикации.

Примечание.

Реестр контейнеров Azure (ACR) не поддерживает acr import импорт изображений, подписанных с помощью Docker Content Trust (DCT). По дизайну подписи не отображаются после импорта, а нотарий версии 2 сохраняет эти подписи как артефакты.

Доверенные образы

Функция доверия к содержимому поддерживает теги образов в репозитории. В таких репозиториях могут находиться как подписанные, так и неподписанные теги. Например, вы подписали образы myimage:stable и myimage:latest, но не подписали myimage:dev.

Ключи подписывания

Управление функцией доверия к содержимому осуществляется с помощью набора ключей подписывания, которые связаны с конкретным репозиторием в реестре. Есть несколько типов таких ключей, с помощью которых Docker-клиенты и ваш реестр управляют доверием к тегам в репозитории. Если функция доверия к содержимому включена и интегрирована в конвейер публикации и получения в контейнере, следует управлять этими ключами с осмотрительностью. Подробные сведения см. в разделе Управление ключами этой статьи, а также на странице Manage keys for content trust (Управление ключами функции доверия к содержимому) документации Docker.

Совет

Здесь представлен общий обзор модели доверия к содержимому в Docker. Более подробное описание см. в статье Content trust in Docker (Функция доверия к содержимому в Docker).

Включение доверия к содержимому в реестре

Сначала необходимо включить функцию доверия к содержимому на уровне реестра. После этого клиенты (пользователи или службы) смогут отправлять подписанные образы в ваш реестр. Включение доверия не ограничивает использование реестра только получателями с этой функцией. Получатели без нее используют ваш реестр как обычно. Но, если у них эта функция включена, для них отображаются только подписанные образы в вашем реестре.

Сначала перейдите в реестр на портале Azure. В разделе Политики последовательно выберите Доверие к содержимому>Включено>Сохранить. Можно также выполнить команду az acr config content-trust update в Azure CLI.

Screenshot shows enabling content trust for a registry in the Azure portal.

Включение доверия к содержимому в клиенте

Чтобы работать с доверенными образами, функция доверия к содержимому в Docker-клиенте должна быть включена и у издателей, и у получателей. Издатель может подписывать образы, отправляемые в реестр с функцией доверия. А получатель, включая функцию доверия, ограничивает отображение образов в реестре только подписанными. В Docker-клиенте эта функция по умолчанию отключена, но ее можно включить для сеанса оболочки или для команды.

Чтобы включить доверие для сеанса оболочки, установите для переменной среды DOCKER_CONTENT_TRUST значение 1. Пример для оболочки bash:

# Enable content trust for shell session
export DOCKER_CONTENT_TRUST=1

Если нужно включить или отключить доверие для одной команды, аргумент --disable-content-trust поддерживается несколькими командами Docker. Пример включения доверия для одной команды:

# Enable content trust for single command
docker build --disable-content-trust=false -t myacr.azurecr.io/myimage:v1 .

Если доверие уже включено для сеанса оболочки и нужно отключить его для одной команды, используйте следующий код:

# Disable content trust for single command
docker build --disable-content-trust -t myacr.azurecr.io/myimage:v1 .

Выдача разрешения на подписывание образов

Только пользователи или системы с разрешением на подписывание могут отправлять доверенные образы в ваш реестр. Чтобы предоставить пользователю разрешение на отправку доверенного образа (или системе с помощью субъекта-службы), предоставьте удостоверений AcrImageSigner Microsoft Entra роли. в дополнение к роли AcrPush (или ее аналогу), необходимой для отправки образов в реестр. Дополнительные сведения см. в разделе Роли и разрешения реестра контейнеров Azure.

Важно!

Вы не можете предоставить разрешение на отправку доверенного образа следующим административным учетным записям:

Примечание.

Начиная с июля 2021 г., роль AcrImageSigner включает как Microsoft.ContainerRegistry/registries/sign/write действие, так и действие с данными Microsoft.ContainerRegistry/registries/trustedCollections/write.

Далее описано, как назначить роль AcrImageSigner на портале Azure и в инфраструктуре Azure CLI.

Портал Azure

  1. Выберите Управление доступом (IAM) .

  2. Выберите Добавить>Добавить назначение ролей, чтобы открыть страницу "Добавление назначения ролей".

  3. Назначьте следующую роль. В этом примере роль назначается отдельному пользователю. Подробные инструкции см. в статье Назначение ролей Azure с помощью портала Microsoft Azure.

    Параметр Значение
    Роль AcrImageSigner
    Назначить доступ для User
    Участники Alain

    Add role assignment page in Azure portal.

Azure CLI

Чтобы выдать разрешение на подписывание с помощью Azure CLI, назначьте роль AcrImageSigner пользователю из вашего реестра. Команда имеет следующий формат.

az role assignment create --scope <registry ID> --role AcrImageSigner --assignee <user name>

Например, чтобы предоставить роль пользователю без прав администратора, вы можете выполнить следующие команды в сеансе Azure CLI с проверкой подлинности. Измените значение REGISTRY в соответствии с именем реестра контейнеров Azure.

# Grant signing permissions to authenticated Azure CLI user
REGISTRY=myregistry
REGISTRY_ID=$(az acr show --name $REGISTRY --query id --output tsv)

az role assignment create --scope $REGISTRY_ID --role AcrImageSigner --assignee azureuser@contoso.com

Также можно выдать права на отправку образов в реестр субъекту-службе. Субъект-службу можно использовать для систем сборки и других автоматических систем, чтобы отправлять доверенные образы в ваш реестр. Действия аналогичны выдаче разрешения пользователю, только в значении --assignee указывается идентификатор субъекта-службы.

az role assignment create --scope $REGISTRY_ID --role AcrImageSigner --assignee <service principal ID>

В <service principal ID> можно указать appId или objectId субъекта-службы или одно из его имен servicePrincipalNames. Дополнительные сведения о работе с субъектами-службами и Реестром контейнеров Azure см. в статье Аутентификация в реестре контейнеров Azure с помощью субъектов-служб.

Важно!

После изменения роли выполните az acr login для обновления локального маркера идентификации для Azure CLI, чтобы новые роли вступили в действие. Дополнительные сведения о проверке ролей для удостоверения см. в разделах Добавление или удаление назначений ролей Azure с помощью Azure CLI и Устранение неполадок Azure RBAC.

Отправка доверенного образа

Чтобы отправить доверенный тег образа в реестр контейнеров, включите функцию доверия к содержимому и отправьте образ с помощью docker push. После того как отправка с подписанным тегом завершится в первый раз, вас попросят создать парольную фразу как для корневого ключа подписи, так и для ключа подписи репозитория. Оба ключа создаются и хранятся локально на вашем компьютере.

$ docker push myregistry.azurecr.io/myimage:v1
[...]
The push refers to repository [myregistry.azurecr.io/myimage]
ee83fc5847cb: Pushed
v1: digest: sha256:aca41a608e5eb015f1ec6755f490f3be26b48010b178e78c00eac21ffbe246f1 size: 524
Signing and pushing trust metadata
You are about to create a new root signing key passphrase. This passphrase
will be used to protect the most sensitive key in your signing system. Please
choose a long, complex passphrase and be careful to keep the password and the
key file itself secure and backed up. It is highly recommended that you use a
password manager to generate the passphrase and keep it safe. There will be no
way to recover this key. You can find the key in your config directory.
Enter passphrase for new root key with ID 4c6c56a:
Repeat passphrase for new root key with ID 4c6c56a:
Enter passphrase for new repository key with ID bcd6d98:
Repeat passphrase for new repository key with ID bcd6d98:
Finished initializing "myregistry.azurecr.io/myimage"
Successfully signed myregistry.azurecr.io/myimage:v1

После первого применения docker push с включенным доверием Docker-клиент будет использовать тот же корневой ключ для последующих отправок. Каждый раз при отправке в тот же репозиторий нужно вводить только ключ репозитория. При отправке в новый репозиторий создайте парольную фразу для нового ключа репозитория.

Извлечение доверенного образа

Чтобы извлечь доверенный образ, включите функцию доверия к содержимому и выполните команду docker pull в обычном режиме. Для извлечения надежных образов обычным пользователям будет достаточно роли AcrPull. Дополнительные роли, например AcrImageSigner, не требуются. Получатели с включенным доверием могут извлекать только образы с подписанными тегами. Пример извлечения подписанного тега:

$ docker pull myregistry.azurecr.io/myimage:signed
Pull (1 of 1): myregistry.azurecr.io/myimage:signed@sha256:0800d17e37fb4f8194495b1a188f121e5b54efb52b5d93dc9e0ed97fce49564b
sha256:0800d17e37fb4f8194495b1a188f121e5b54efb52b5d93dc9e0ed97fce49564b: Pulling from myimage
8e3ba11ec2a2: Pull complete
Digest: sha256:0800d17e37fb4f8194495b1a188f121e5b54efb52b5d93dc9e0ed97fce49564b
Status: Downloaded newer image for myregistry.azurecr.io/myimage@sha256:0800d17e37fb4f8194495b1a188f121e5b54efb52b5d93dc9e0ed97fce49564b
Tagging myregistry.azurecr.io/myimage@sha256:0800d17e37fb4f8194495b1a188f121e5b54efb52b5d93dc9e0ed97fce49564b as myregistry.azurecr.io/myimage:signed

Если клиент с включенным доверием к контенту пытается извлечь неподписанный тег, операция завершается ошибкой, подобной следующей:

$ docker pull myregistry.azurecr.io/myimage:unsigned
Error: remote trust data does not exist

Сопутствующие ресурсы

При выполнении docker pull клиент Docker использует ту же библиотеку, что и в Notary CLI, для запроса на сопоставление хэша извлекаемого тега с помощью SHA-256. После проверки подписей в данных доверия клиент дает подсистеме Docker команду выполнить «Вытягивание по хэш-коду». Во время вытягивания подсистема использует контрольную сумму SHA-256 как адрес содержимого для запроса и проверки манифеста образа из реестра контейнеров Azure.

Примечание.

Реестр контейнеров Azure официально не поддерживает интерфейс командной строки нотариуса, но совместим с API сервера нотариуса, который входит в состав Docker Desktop. В настоящее время рекомендуется Notary версии 0.6.0.

Управление ключами

Как указано в выходных данных docker push, наиболее важным при первой отправке доверенного образа является корневой ключ. Не забудьте создать для него резервную копию и храните ее в безопасном расположении. По умолчанию Docker-клиент хранит ключи подписывания здесь:

~/.docker/trust/private

Создайте резервную копию корневых ключей и ключей репозитория, поместив их в архив, и храните в безопасном расположении. Пример (bash):

umask 077; tar -zcvf docker_private_keys_backup.tar.gz ~/.docker/trust/private; umask 022

Другие ключи, наряду с корневыми ключами и ключами репозитория, созданными локально, создаются и хранятся в Реестре контейнеров Azure при отправке доверенного образа. Подробное описание различных типов ключей, а также советы по управлению ими в функции доверия к содержимому в Docker см. на странице Manage keys for content trust (Управление ключами функции доверия к содержимому) документации Docker.

Потеря корневого ключа

В случае потери корневого ключа вы теряете доступ к подписанным этим ключом тегам из любого репозитория. Реестр контейнеров Azure не восстанавливает доступ к таким тегам. Чтобы удалить все доверенные данные (подписи) в реестре, отключите, а затем снова включите доверие к содержимому для этого реестра.

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

При отключении и повторном включении доверия к содержимому в реестре удаляются все доверенные данные всех подписанных тегов в каждом репозитории реестра. Это действие невозможно отменить — Реестр контейнеров Azure не восстанавливает удаленные доверенные данные. Отключение доверия не приводит к удалению самих образов.

Чтобы отключить доверие к содержимому, перейдите в реестр на портале Azure. В разделе Политики последовательно выберите Доверие к содержимому>Отключено>Сохранить. Появится предупреждение о потере всех подписей в реестре. Выберите ОК, чтобы удалить все подписи в реестре без возможности восстановления.

Disabling content trust for a registry in the Azure portal

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

  • См. в разделе Доверие содержимого в Docker дополнительную информацию о доверии содержимого, включая команды доверия docker и делегирование доверия. В этой статье мы затронули лишь ключевые моменты обширной темы доверия к содержимому, которая более подробно рассматривается в документации Docker.

  • Пример того, как применяется функция доверия к содержимому при создании и отправке образа Docker, см. в документации по Azure Pipelines.