Зеркала провайдеров в реестрах 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 распознал его как манифест выпуска провайдера.

Затем 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​

Для сборки и отправки манифестов и блобов провайдера мы рекомендуем использовать интерфейс командной строки, предоставляемый проектом 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, как показано в примере в начале этой страницы.