Передача артефактов в другой реестр

Что такое передача ACR?

Передача ACR — это функция реестра контейнеров Azure для передачи образов контейнеров и других артефактов OCI между реестрами, которые могут находиться в разных облаках или физически отключенных средах. Передача выполняется с помощью промежуточной учетной записи хранения:

  • Артефакты из исходного реестра экспортируются в BLOB-объект в исходной учетной записи хранения.
  • Блоб копируется из исходной учетной записи хранения в целевую учетную запись хранения (при необходимости через границы сети).
  • Объект Blob в целевой учетной записи хранения импортируется в виде артефактов в целевом реестре

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

Как это работает — конвейеры и запуски конвейеров

Передача ACR состоит из трех типов ресурсов, которые работают совместно для репликации артефактов между реестрами:

  • ExportPipeline — долговременный ресурс, связанный с источником реестра и учетной записью хранения. Определяет, где записываются экспортированные артефакты (контейнер Blob-объектов для хранения) и как конвейер аутентифицирует доступ к хранилищу.

  • ImportPipeline — это долговременный ресурс, связанный с целевым реестром и учетной записью хранения. Он определяет, откуда читать артефактные блобы и как конвейер проводит аутентификацию в хранилище. По умолчанию ImportPipeline включает триггер источника, который автоматически импортирует новые объекты blob по мере их поступления.

  • PipelineRun — однократный ресурс выполнения, который активирует либо ExportPipeline, либо ImportPipeline. Для экспорта необходимо указать, какие артефакты (по тегу или дайджесту) экспортируются. Для импорта необходимо указать, какой блоб импортировать. В настоящее время с помощью каждого ресурса PipelineRun можно передать не более 50 артефактов.

Думайте о конвейерах как о конфигурации, а о выполнении конвейеров как об исполнении.

Внимание

ACR Transfer поддерживает артефакты с размером слоя до 8 ГБ из-за технических ограничений.

Режимы доступа к хранилищу

ACR Transfer поддерживает два режима доступа для проверки подлинности конвейеров к учетным записям хранения:

  • Маркер SAS - Конвейер подтверждает подлинность для учетной записи хранения с помощью маркера SAS с подписанным URL-адресом, который хранится как секрет в Azure Key Vault. Управляемое удостоверение конвейера считывает секрет маркера SAS из хранилища ключей.

  • Управляемое удостоверение — Конвейер проходит проверку подлинности непосредственно в учетной записи хранения с помощью управляемого удостоверения Microsoft Entra (назначаемого системой или назначаемого пользователем). Для доступа к хранилищу не требуется маркер Key Vault или SAS.

При создании конвейеров укажите с помощью параметра --storage-access-mode (CLI) или свойства storageAccessMode (шаблонов ARM) режим. В выбранном режиме определяется, какие предварительные требования необходимо выполнить ниже.

Схемы архитектуры

На следующих схемах показана архитектура для настройки конвейера экспорта и импорта. В этом примере демонстрируется передача образов через промежуточную учетную запись хранения для сценариев передачи образов между облаками или несколькими клиентами без прямого доступа ACR к ACR.

Режим управляемого удостоверения:

Source Cloud                                                                     Target Cloud
+-------------------------------------------------+                              +-------------------------------------------------+
|                                                 |                              |                                                 |
|  +-----------------------------------+          |                              |          +-----------------------------------+  |
|  | Source ACR                        |          |                              |          | Target ACR                        |  |
|  +-----------------------------------+          |                              |          +-----------------------------------+  |
|                   |                             |                              |                       ^                         |
|                   v                             |                              |                       |                         |
|  +-----------------------------------+          |                              |          +-----------------------------------+  |
|  | ExportPipeline                    |          |                              |          | ImportPipeline                    |  |
|  +-----------------------------------+          |                              |          +-----------------------------------+  |
|                   |                             |                              |                       ^                         |
|                   |                             |                              |                       |                         |
|                   |                             |                              |                       |                         |
|                   | Pipeline accesses           |                              |                       | Pipeline accesses       |
|                   | storage account directly    |                              |                       | storage account         |
|                   | (using Pipeline's Managed   |                              |                       | directly (using         |
|                   | Identity) to export image   |                              |                       | Pipeline's Managed      |
|                   |                             |                              |                       | Identity) to import     |
|                   | RBAC: Storage Blob Data     |                              |                       | image                   |
|                   | Contributor                 |                              |                       |                         |
|                   |                             |                              |                       | RBAC: Storage Blob Data |
|                   |                             |                              |                       | Contributor             |
|                   |                             |                              |                       |                         |
|                   v                             |                              |                       |                         |
|  +-----------------------------------+          |      Cross-Cloud or          |          +-----------------------------------+  |
|  | Storage Account                   |----------|----- Cross-Tenant -----------|--------->| Storage Account                   |  |
|  | (Blob Container)                  |          |      Syndication Process     |          | (Blob Container)                  |  |
|  +-----------------------------------+          |                              |          +-----------------------------------+  |
|                                                 |                              |                                                 |
+-------------------------------------------------+                              +-------------------------------------------------+

Режим маркера SAS:

Source Cloud                                                                     Target Cloud
+-------------------------------------------------+                              +-------------------------------------------------+
|                                                 |                              |                                                 |
|  +-----------------------------------+          |                              |          +-----------------------------------+  |
|  | Source ACR                        |          |                              |          | Target ACR                        |  |
|  +-----------------------------------+          |                              |          +-----------------------------------+  |
|                   |                             |                              |                       ^                         |
|                   v                             |                              |                       |                         |
|  +-----------------------------------+          |                              |          +-----------------------------------+  |
|  | ExportPipeline                    |          |                              |          | ImportPipeline                    |  |
|  +-----------------------------------+          |                              |          +-----------------------------------+  |
|               |           |                     |                              |                   ^           |                 |
|               |           |                     |                              |                   |           |                 |
|               |           | Access Key Vault    |                              |                   |           | Access Key      |
|               |           | (using Pipeline's   |                              |                   |           | Vault (using    |
|               |           | Managed Identity)   |                              |                   |           | Pipeline's      |
|               |           | to fetch Storage    |                              |                   |           | Managed         |
|               |           | SAS Secret          |                              |                   |           | Identity) to    |
|               |           v                     |                              |                   |           | fetch Storage   |
|               |  +------------------------+     |                              |                   |           | SAS Secret      |
|               |  | Source Key Vault       |     |                              |                   |           v                 |
|               |  | (SAS Token Secret)     |     |                              |                   |  +------------------------+ |
|               |  +------------------------+     |                              |                   |  | Target Key Vault       | |
|               |                                 |                              |                   |  | (SAS Token Secret)     | |
|               | Pipeline accesses storage       |                              |                   |  +------------------------+ |
|               | account using SAS Secret to     |                              |                   |                             |
|               | export image                    |                              |                   | Pipeline accesses storage   |
|               |                                 |                              |                   | account using SAS Secret    |
|               |                                 |                              |                   | to import image             |
|               |                                 |                              |                   |                             |
|               v                                 |                              |                   |                             |
|  +-----------------------------------+          |      Cross-Cloud or          |          +-----------------------------------+  |
|  | Storage Account                   |----------|----- Cross-Tenant -----------|--------->| Storage Account                   |  |
|  | (Blob Container)                  |          |      Syndication Process     |          | (Blob Container)                  |  |
|  +-----------------------------------+          |                              |          +-----------------------------------+  |
|                                                 |                              |                                                 |
+-------------------------------------------------+                              +-------------------------------------------------+

Рассмотрим ваш случай использования

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

Для других сценариев рассмотрим следующие варианты:

  • Если вы хотите скопировать образы из реестров контейнеров в подключенных облаках, включая Docker Hub и других поставщиков облачных служб, рекомендуется импортировать образ .
  • Если вы хотите кэшировать образы из общедоступных реестров для повышения производительности извлечения, см. раздел "Кэш артефактов".

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

Общие предварительные требования (оба режима доступа к хранилищу)

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

  • Реестры контейнеров. Вам потребуется исходный реестр с артефактами для передачи и целевой реестр. Оба реестра должны находиться на уровне служб Premium . Передача данных ACR предназначена для перемещения между физически разобщенными облаками. Для тестирования исходные и целевые реестры могут находиться в одной или другой подписке Azure, клиенте Microsoft Entra или облаке.

    Сведения об уровнях служб реестра и ограничениях см. в статье Уровни службы Реестра контейнеров Azure. Если вам нужно создать реестр, см. инструкции в статье Краткое руководство. Создание закрытого реестра контейнеров с помощью Azure CLI.

  • Учетные записи хранения. Создайте исходную и целевую учетные записи хранения в любой подписке и любом расположении. Для тестирования можно использовать ту же самую подписку или несколько подписок, что и для исходного и целевого реестров. При работе с разными облаками обычно создается отдельная учетная запись хранения в каждом из них.

    При необходимости создайте учетные записи хранения с помощью Azure CLI или других инструментов. В каждой учетной записи следует создать контейнер BLOB-объектов для передачи артефактов. Например, создайте контейнер с названием transfer.

Дополнительные предварительные условия для режима токена SAS

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

  • Хранилища ключей — создание исходных и целевых хранилищ ключей для хранения секретов маркера SAS. Создайте их в той же подписке Azure или подписках Azure, что и для исходных и целевых реестров. В демонстрационных шаблонах и командах в этой статье предполагается, что исходные и целевые хранилища ключей находятся в тех же группах ресурсов, что и исходные и целевые реестры. Такое использование общих групп ресурсов не обязательно, но упрощает шаблоны и команды, которые используются в этой статье.

    При необходимости создайте хранилища ключей с помощью Azure CLI или других инструментов.

  • Маркеры SAS. Необходимо создать маркеры SAS для контейнеров учетной записи хранения и сохранить их в хранилищах ключей. Дополнительные сведения см. в статье "Создание и хранение маркеров SAS " ниже.

  • Доступ к Key Vault . Управляемое удостоверение конвейера должно иметь secret get разрешения политики доступа в Key Vault для чтения секрета маркера SAS.

Дополнительные предварительные требования для режима управляемого удостоверения

Если вы планируете использовать режим доступа к хранилищу Managed Identity, вам также необходимо:

  • Назначение ролей RBAC — управляемое удостоверение конвейера (назначаемое системой или назначаемое пользователем) должно иметь соответствующую роль RBAC в учетной записи хранения. Например, назначьте Storage Blob Data Contributor роль, чтобы разрешить конвейеру читать и записывать большие двоичные объекты.

  • Требование к версии API - Для режима управляемого удостоверения требуется версия API 2025-06-01-preview или более поздняя (для шаблонов ARM) или расширение Azure CLI версии 2.0.0 или более поздней (для CLI).

Замечание

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

Переменные среды

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

SOURCE_RG="<source-resource-group>"
TARGET_RG="<target-resource-group>"
SOURCE_KV="<source-key-vault>"  # Only needed for SAS Token mode
TARGET_KV="<target-key-vault>"  # Only needed for SAS Token mode
SOURCE_SA="<source-storage-account>"
TARGET_SA="<target-storage-account>"

Полезная информация

  • ExportPipeline и ImportPipeline обычно будут находиться в разных клиентах Microsoft Entra, связанных с исходными и целевыми облаками. Для этого сценария требуются отдельные управляемые идентичности и хранилища ключей (при использовании режима SAS Token) для ресурсов экспорта и импорта. Для тестирования эти ресурсы можно разместить в одном облаке, разделяя удостоверения.
  • По умолчанию шаблоны ExportPipeline и ImportPipeline позволяют включить управляемое удостоверение, назначаемое системой. Шаблоны также поддерживают предоставленное пользователем удостоверение.
    • При использовании режима SAS Token идентификатор считывает секреты токенов SAS из хранилища ключей.
    • При использовании режима управляемого удостоверения удостоверение проходит проверку подлинности непосредственно в учетной записи хранения.

Создание и хранение маркеров SAS

Замечание

Следующая настройка маркера SAS требуется только при использовании режима доступа к хранилищу маркеров SAS . Если вы планируете использовать режим доступа к хранилищу управляемых удостоверений , пропустите этот раздел и перейдите к следующим шагам.

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

Внимание

Хотя ACR Transfer будет работать с вручную сгенерированным токеном SAS, хранящимся в секрете Key Vault, для рабочих нагрузок мы настоятельно рекомендуем использовать секреты определения SAS, управляемые хранилищем Key Vault.

Создание маркера SAS для экспорта

Выполните команду az storage container generate-sas, чтобы создать маркер SAS для контейнера в исходной учетной записи хранения, которая используется для экспорта артефактов.

Рекомендуемые разрешения для маркера: чтение, запись, вывод списка, добавление.

В примере ниже выходные данные команды присваиваются переменной среды EXPORT_SAS с префиксом "?". Обновите значение --expiry для своей среды:

EXPORT_SAS=?$(az storage container generate-sas \
  --name transfer \
  --account-name $SOURCE_SA \
  --expiry 2027-01-01 \
  --permissions alrw \
  --https-only \
  --output tsv)

Хранение маркера SAS для экспорта

Сохраните маркер SAS в исходном хранилище ключей Azure с помощью команды az keyvault secret set:

az keyvault secret set \
  --name acrexportsas \
  --value $EXPORT_SAS \
  --vault-name $SOURCE_KV

Создание маркера SAS для импорта

Выполните команду az storage container generate-sas, чтобы создать маркер SAS для контейнера в целевой учетной записи хранения, которая используется для импорта артефактов.

Рекомендуемые разрешения для маркера: Чтение, Удаление, Список.

В примере ниже выходные данные команды присваиваются переменной среды IMPORT_SAS с префиксом "?". Обновите значение --expiry для своей среды:

IMPORT_SAS=?$(az storage container generate-sas \
  --name transfer \
  --account-name $TARGET_SA \
  --expiry 2027-01-01 \
  --permissions dlr \
  --https-only \
  --output tsv)

Хранение токена SAS для импорта

Сохраните маркер SAS в целевом хранилище ключей Azure с помощью команды az keyvault secret set:

az keyvault secret set \
  --name acrimportsas \
  --value $IMPORT_SAS \
  --vault-name $TARGET_KV

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

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

При возникновении проблем см. инструкции по устранению неполадок при передаче ACR .

  • Last updated on