Spec-Zone.ru › OpenTofu 1.10

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

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

Альтернативные способы установки провайдеров настраиваются в составе конфигурации интерфейса командной строки 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 получает список всех тегов репозитория. Допустимое имя тега должно представлять собой номер версии в формате, соответствующем синтаксису Semantic Versioning 2.0.0, за исключением того, что в имени тега для отделения необязательной части «метаданных сборки» вместо знака плюс (+) следует использовать символ подчеркивания (_).

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

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

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

Свойству artifactType манифеста индекса необходимо задать значение application/vnd.opentofu.provider, чтобы OpenTofu мог распознать его как манифест выпуска провайдера.

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

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

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

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

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

Примечание

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

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

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

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

Если вы впервые устанавливаете и используете 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. Перейдите по ссылке «Repository» на панели навигации, чтобы открыть репозиторий провайдера на GitHub.
  3. Найдите в панели навигации репозитория заголовок «Releases» и выберите последний выпуск — на момент написания этой документации это был 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 и создать его манифест:

Блок кода
$ oras push \
    --artifact-type application/vnd.opentofu.provider-target \
    --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 не позволяет напрямую создавать и отправлять манифест индекса, однако созданная на предыдущем этапе «структура образа OCI» содержит собственный манифест индекса. Его можно адаптировать для отправки в удаленный репозиторий.

Сначала скопируйте файл индекса структуры образа в другой файл, чтобы отредактировать его, не повредив каталог структуры образа:

Блок кода
$ cp tmp-layout/index.json terraform-provider-tls_4.0.6.json

Откройте новый файл terraform-provider-tls_4.0.6.json в удобном текстовом редакторе. Вероятно, документ JSON будет «минифицирован», поэтому перед продолжением можно попросить редактор отформатировать его для удобства чтения.

В файле должно быть свойство JSON "mediaType" : "application/vnd.oci.image.index.v1+json", указывающее, что это манифест индекса OCI. После него добавьте новое свойство JSON "artifactType":"application/vnd.opentofu.provider", указывающее, что это индекс артефакта провайдера OpenTofu.

В файле также есть свойство "manifests", описывающее каждый из ранее созданных манифестов для отдельных платформ. Каждый из этих объектов-дескрипторов должен содержать свойство "platform", указывающее платформу, для которой предназначен манифест. Например:

Блок кода
{
  "artifactType": "application/vnd.opentofu.provider-target",
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "digest": "sha256:01d3ccf9747dd604ebaa314efbacf12e18a248f8bf1c783f5cbb220754954e67",
  "size": 606,
  "platform": {
    "os": "linux",
    "architecture": "amd64"
  }
}

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

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

Блок кода
$ oras manifest push --oci-layout tmp-layout:4.0.6 terraform-provider-tls_4.0.6.json 
Uploading da13ebaa32ba application/vnd.oci.image.index.v1+json
Uploaded  da13ebaa32ba application/vnd.oci.image.index.v1+json
Pushed: [oci-layout] tmp-layout:4.0.6
Digest: sha256:da13ebaa32ba856d75da18e38daabc7a65ac8853230dfcc817f8ccbac15b639a

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

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

Copyright (c) The OpenTofu Authors
Copyright (c) 2014 HashiCorp, Inc.
Mozilla Public License, version 2.0
https://opentofu.org/docs/v1.10/cli/oci_registries/provider-mirror/

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API