Зеркала провайдеров в реестрах OCI

«Зеркало провайдера» — это дополнительное место, где размещена копия провайдера, используемая вместо обращения к основному реестру провайдеров OpenTofu. Создание локального зеркала некоторых или всех используемых вами провайдеров позволяет снизить расходы на передачу данных и упростить запуск OpenTofu в изолированных от интернета средах, не имеющих доступа к каким-либо службам через общедоступный интернет.

Альтернативные способы установки провайдеров настраиваются в составе конфигурации CLI OpenTofu. Установку из реестров OCI можно настроить с помощью блока oci_mirror в составе явной конфигурации способа установки.

provider_installation {
  oci_mirror {
    repository_template = "example.com/opentofu-providers/${namespace}/${type}"
    include             = ["registry.opentofu.org/*/*"]
  }
}

В приведённом выше примере указано, что любой провайдер из основного реестра OpenTofu должен устанавливаться из репозитория в реестре OCI. Адрес репозитория формируется динамически на основе компонентов адреса источника провайдера.

Например, адрес источника провайдера hashicorp/tls — это сокращённая запись адреса registry.opentofu.org/hashicorp/tls, поэтому он соответствует настроенному выше правилу способа установки: hashicorp выступает в роли «пространства имён», а tls — в роли «типа». Следовательно, согласно этой конфигурации, провайдер нужно установить из репозитория с именем opentofu-providers/hashicorp/tls в реестре OCI, работающем по адресу example.com.

Аргументы способа установки oci_mirror​

• repository_template: строковый шаблон в стиле HCL, результатом вычисления которого является адрес репозитория OCI для заданного провайдера.

  В шаблоне доступны следующие символы для подстановки:

  • hostname: имя хоста основного реестра, к которому относится провайдер, например registry.opentofu.org.
  • namespace: пространство имён, к которому относится провайдер в исходном реестре, например hashicorp в приведённом выше примере.
  • type: имя «типа» провайдера — последняя часть адреса источника, уникальная в пределах определённого пространства имён, например tls в приведённом выше примере.

  Шаблон должен включать подстановку для каждого компонента адреса источника провайдера, который не ограничен точным значением аргумента include. Например, значение include = ["registry.opentofu.org/*/*"] задаёт единственное допустимое имя хоста, но оставляет пространство имён и тип неограниченными. Поэтому шаблон должен включать подстановки для namespace и type, но использовать hostname необязательно.

• include и exclude: списки шаблонов адресов источников провайдеров, которые вместе определяют подмножество провайдеров, обрабатываемых этим способом установки, как описано в разделе «Явная конфигурация способа установки».

Содержимое репозитория OCI​

Выбранный с помощью repository_template репозиторий OCI должен содержать данные в определённой структуре, которая позволяет OpenTofu распознавать метаданные всех доступных версий провайдера и соответствующих им дистрибутивных пакетов.

Имена тегов​

Сначала OpenTofu получает список всех тегов в репозитории. Допустимое имя тега должно быть номером версии в формате, соответствующем синтаксису семантического версионирования 2.0.0, однако для разделения необязательной части «метаданных сборки» в имени тега необходимо использовать символ подчёркивания (_) вместо символа плюса (+).

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

Структура манифеста​

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

Для распознавания манифеста как представляющего выпуск провайдера свойство artifactType в манифесте индекса должно иметь значение application/vnd.opentofu.provider.

Затем OpenTofu ищет в массиве manifests дескриптор манифеста, у которого artifactType имеет значение application/vnd.opentofu.provider-target, а свойство platform соответствует операционной системе и архитектуре, для которых скомпилирована сама OpenTofu.

Выбранный дескриптор используется для получения манифеста образа, представляющего файлы и метаданные, необходимые для установки выбранной версии провайдера на текущей платформе. В этом манифесте свойство artifactType также должно иметь значение application/vnd.opentofu.provider-target, соответствующее дескриптору, с помощью которого был получен манифест.

Массив layers манифеста образа должен содержать ровно один дескриптор, у которого mediaType имеет значение archive/zip. Он должен ссылаться на блоб, содержащий пакет .zip, в точности совпадающий с тем, который был бы возвращён для той же версии провайдера на той же платформе при установке из исходного реестра провайдера.

Наконец, OpenTofu получает указанный блоб и извлекает архив .zip в каталог кэша провайдеров, чтобы он был доступен для последующих команд рабочего процесса, таких как tofu apply.

Сборка и отправка манифестов провайдера​

Установка и настройка ORAS​

Для сборки и отправки манифестов и блобов провайдера мы рекомендуем использовать CLI-инструмент, предоставляемый проектом ORAS. В приведённых ниже инструкциях используются возможности, впервые появившиеся в ORAS v1.3.0.

Если вы впервые устанавливаете и используете ORAS и собираетесь отправлять данные в реестр OCI, для которого требуется аутентификация, сначала необходимо получить учётные данные для этого репозитория с помощью команды oras login.

Локальная структура образа OCI​

Сборка манифестов провайдера OpenTofu с помощью ORAS требует нескольких шагов. Поэтому мы рекомендуем сначала отправить различные артефакты в локальный каталог файловой системы — так называемую структуру образа OCI, — а затем отправить все полученные объекты в целевой репозиторий за один раз. Это позволит не показывать промежуточные шаги другим пользователям удалённого репозитория.

В примерах командной строки в следующих разделах используется параметр ORAS --oci-layout, указывающий, что целью каждой операции является локальный каталог файловой системы с именем tmp-layout в текущем рабочем каталоге. Вместо tmp-layout можно указать любой желаемый путь, если во всех командах используется один и тот же путь.

Манифесты образов для одной платформы​

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

Сначала получите официальные дистрибутивные пакеты .zip провайдера, который вы собираетесь повторно публиковать. Для провайдеров из официального реестра OpenTofu можно найти ссылку на репозиторий провайдера на GitHub и скачать артефакты .zip из одного из его выпусков.

Например, чтобы подготовить к повторной упаковке провайдер hashicorp/tls:

1. Откройте страницу провайдера hashicorp/tls в реестре.
2. Перейдите по ссылке «Репозиторий» на панели навигации, чтобы открыть репозиторий провайдера на GitHub.
3. Найдите в панели навигации репозитория раздел «Выпуски» и выберите последний выпуск — на момент написания это был v4.0.6.
4. Загрузите файлы .zip для каждой платформы, которую вы собираетесь включить в зеркало, в новый пустой каталог на локальном компьютере.

После перехода в этот каталог в оболочке вы сможете вывести список всех загруженных пакетов:

$ ls -1
terraform-provider-tls_4.0.6_darwin_amd64.zip
terraform-provider-tls_4.0.6_linux_386.zip
terraform-provider-tls_4.0.6_linux_amd64.zip
terraform-provider-tls_4.0.6_linux_arm.zip
terraform-provider-tls_4.0.6_linux_arm64.zip
terraform-provider-tls_4.0.6_windows_386.zip
terraform-provider-tls_4.0.6_windows_amd64.zip
terraform-provider-tls_4.0.6_windows_arm.zip
terraform-provider-tls_4.0.6_windows_arm64.zip

Для каждого пакета по очереди используйте oras push, чтобы скопировать архив .zip в локальную структуру образа OCI и создать для него манифест. Укажите соответствующий параметр --artifact-platform, исходя из двух последних частей имени файла пакета:

$ oras push \
    --artifact-type application/vnd.opentofu.provider-target \
    --artifact-platform linux/amd64 \
    --oci-layout tmp-layout:linux_amd64 \
    terraform-provider-tls_4.0.6_linux_amd64.zip:archive/zip

✓ Uploaded  terraform-provider-tls_4.0.6_linux_amd64.zip
  └─ sha256:5f12d51fa9e87b6d29275fa58d1cd8681c0177a1d3a71a4e6c78ad7b011fa065
✓ Uploaded  application/vnd.oci.image.config.v1+json
  └─ sha256:9d99a75171aea000c711b34c0e5e3f28d3d537dd99d110eafbfbc2bd8e52c2bf
✓ Uploaded  application/vnd.oci.image.manifest.v1+json
  └─ sha256:01d3ccf9747dd604ebaa314efbacf12e18a248f8bf1c783f5cbb220754954e67
Pushed [oci-layout] tmp-layout:linux_amd64
ArtifactType: application/vnd.opentofu.provider-target
Digest: sha256:01d3ccf9747dd604ebaa314efbacf12e18a248f8bf1c783f5cbb220754954e67

Значение Digest в конце вывода — это идентификатор манифеста для конкретной платформы. Дайджест в приведённом выше примере является заполнителем; для каждого отдельного пакета провайдера результат будет отличаться.

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

$ oras repo tags --oci-layout tmp-layout
darwin_amd64
linux_386
linux_amd64
linux_arm
linux_arm64
windows_386
windows_amd64
windows_arm
windows_arm64

Манифест индекса для нескольких платформ​

Артефакты для конкретных платформ, созданные в предыдущем разделе, необходимо объединить в одном манифесте индекса — манифесте верхнего уровня, который впоследствии будет связан с тегом в удалённом репозитории.

Используйте oras manifest index create, чтобы создать манифест индекса со ссылками на все артефакты, помеченные тегами в предыдущем разделе:

$ oras manifest index create \
    --artifact-type="application/vnd.opentofu.provider" \
    --oci-layout tmp-layout:4.0.6 \
    darwin_amd64 \
    linux_386 \
    linux_amd64 \
    linux_arm \
    linux_arm64 \
    windows_386 \
    windows_amd64 \
    windows_arm \
    windows_arm64

Аргумент tmp-layout:4.0.6 указывает, что этот манифест нужно сначала создать в том же локальном каталоге структуры образа и пометить тегом 4.0.6, соответствующим номеру версии выпуска провайдера.

Список аргументов «os_arch» соответствует тегам, созданным в предыдущем разделе, и указывает, какие артефакты нужно включить в манифест.

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

$ oras repo tags --oci-layout tmp-layout
4.0.6
darwin_amd64
linux_386
linux_amd64
linux_arm
linux_arm64
windows_386
windows_amd64
windows_arm
windows_arm64

Отправка артефактов в удалённый репозиторий​

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

$ oras cp \
   --from-oci-layout tmp-layout:4.0.6 \
   example.com/opentofu-providers/hashicorp/tls:4.0.6

✓ Copied  terraform-provider-tls_4.0.6_linux_amd64.zip
  └─ sha256:5f12d51fa9e87b6d29275fa58d1cd8681c0177a1d3a71a4e6c78ad7b011fa065
[...]
✓ Copied  application/vnd.oci.image.config.v1+json
  └─ sha256:9d99a75171aea000c711b34c0e5e3f28d3d537dd99d110eafbfbc2bd8e52c2bf
✓ Copied  application/vnd.oci.image.manifest.v1+json
  └─ sha256:01d3ccf9747dd604ebaa314efbacf12e18a248f8bf1c783f5cbb220754954e67
✓ Copied  application/vnd.oci.image.index.v1+json
  └─ sha256:da13ebaa32ba856d75da18e38daabc7a65ac8853230dfcc817f8ccbac15b639a
Copied [oci-layout] tmp-layout:4.0.6 => [registry] example.com/opentofu-providers/hashicorp/tls:4.0.6
Digest: sha256:da13ebaa32ba856d75da18e38daabc7a65ac8853230dfcc817f8ccbac15b639a

ORAS копирует в удалённый реестр всё содержимое, на которое ссылается локальный тег 4.0.6, а затем создаёт удалённый тег 4.0.6, указывающий на те же данные.

Теперь этот провайдер можно использовать, настроив блок установки oci_mirror, как показано в примере в начале этой страницы.