Протокол сетевого зеркала провайдеров

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

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

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

Адреса провайдеров​

Каждому провайдеру OpenTofu соответствует адрес, который однозначно идентифицирует его в OpenTofu. Адрес провайдера имеет синтаксис hostname/namespace/type; подробнее он описан в документации по требованиям к провайдерам.

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

В шаблонах относительных URL-адресов, приведённых далее в этом документе, заполнитель :hostname обозначает имя хоста из адреса запрашиваемого провайдера, а не имя хоста, на котором размещено сетевое зеркало провайдеров.

Базовый URL протокола​

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

Вместо этого раздел установки провайдеров в конфигурации CLI принимает базовый URL напрямую. Указанный URL должен использовать схему https: и оканчиваться косой чертой, чтобы относительные URL-адреса отдельных конечных точек операций разрешались относительно него.

provider_installation {
  network_mirror {
    url = "https://tofu.example.com/providers/"
  }
}

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

В следующих разделах описаны различные операции, которые сервер сетевого зеркала провайдеров должен реализовать для совместимости с установщиком провайдеров OpenTofu CLI. Указанные URL-адреса являются относительными к заданному базовому URL, как описано выше.

В URL-адресах используется соглашение, согласно которому часть пути с префиксом двоеточия : обозначает заполнитель для динамически выбираемого значения, а все остальные части пути являются буквальными. Например, в :hostname/:namespace/:type/index.json первые три части пути являются заполнителями, а третья часть представляет собой строку "index.json".

В примерах запросов в следующих разделах используется пример базового URL зеркала из приведённого выше примера конфигурации CLI.

Аутентификация​

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

Если указанный URL использует нестандартный номер порта (отличный от 443), учётные данные должны быть связаны с именем хоста, включающим номер порта, например tofu.example.com:8443.

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

Список доступных версий​

Эта операция определяет, какие версии доступны в данный момент для указанного провайдера.

Параметры​

• hostname (обязательный): часть адреса запрашиваемого провайдера, содержащая имя хоста.
• namespace (обязательный): часть адреса запрашиваемого провайдера, содержащая пространство имён.
• type (обязательный): часть адреса запрашиваемого провайдера, содержащая тип.

Пример запроса​

curl 'https://tofu.example.com/providers/registry.tofu.io/hashicorp/random/index.json'

Пример ответа​

{
  "versions": {
    "2.0.0": {},
    "2.0.1": {}
  }
}

Свойства ответа​

Успешный результат — это объект JSON с единственным свойством versions, которое должно быть объектом JSON.

Каждое имя свойства объекта versions обозначает доступный номер версии. Значения свойств должны быть объектами, но для этих объектов свойства не определены. Для обеспечения совместимости с будущими версиями рекомендуется оставлять эти объекты пустыми.

Верните 404 Not Found, чтобы сообщить, что в зеркале отсутствует провайдер с указанным адресом.

Список доступных пакетов для установки​

Эта операция возвращает URL-адреса для скачивания и связанные с ними метаданные для пакетов распространения определённой версии провайдера.

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

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

Параметры​

• hostname (обязательный): часть адреса запрашиваемого провайдера, содержащая имя хоста.
• namespace (обязательный): часть адреса запрашиваемого провайдера, содержащая пространство имён.
• type (обязательный): часть адреса запрашиваемого провайдера, содержащая тип.
• version (обязательный): выбранная для скачивания версия. Она будет в точности совпадать с одной из строк версий, возвращённых при предыдущем вызове операции «Список доступных версий».

Пример запроса​

curl 'https://tofu.example.com/providers/registry.tofu.io/hashicorp/random/2.0.0.json'

Пример ответа​

{
  "archives": {
    "darwin_amd64": {
      "url": "terraform-provider-random_2.0.0_darwin_amd64.zip",
      "hashes": [
        "h1:4A07+ZFc2wgJwo8YNlQpr1rVlgUDlxXHhPJciaPY5gs="
      ]
    },
    "linux_amd64": {
      "url": "terraform-provider-random_2.0.0_linux_amd64.zip",
      "hashes": [
        "h1:lCJCxf/LIowc2IGS9TPjWDyXY4nOmdGdfcwwDQCOURQ="
      ]
    }
  }
}

Свойства ответа​

Успешный результат — это объект JSON со свойством archives, которое должно быть объектом JSON.

Каждое имя свойства объекта archives — это идентификатор целевой платформы, состоящий из названий операционной системы и архитектуры, соединённых символом подчёркивания (_).

Каждое значение свойства в объекте archives само является вложенным объектом со следующими свойствами:

• url (обязательное): строка, задающая URL, по которому OpenTofu следует скачать архив .zip с запрашиваемой версией плагина провайдера.

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

  https://tofu.example.com/providers/registry.opentofu.org/hashicorp/random/terraform-provider-random_2.0.0_darwin_amd64.zip

• hashes (необязательное): массив JSON из строк, содержащий одно или несколько хеш-значений для указанного архива. Эти хеши вычисляются с помощью алгоритма хеширования пакетов провайдеров OpenTofu. Сейчас проще всего сформировать их, создав JSON-индексы зеркала с помощью команды tofu providers mirror, описание которой приведено в следующем разделе. Эта команда включает рассчитанные хеши каждого провайдера.

  Если ответ содержит хотя бы один хеш, OpenTofu выберет хеш алгоритма, который считает наиболее надёжным, и проверит, что скачанный пакет ему соответствует. Если ответ не содержит свойства hashes, OpenTofu установит указанный архив без проверки.

OpenTofu CLI будет пытаться скачивать только те версии, которые ранее встречались в ответе на операцию «Список доступных версий».

Зеркало провайдеров в виде статического веб-сайта​

Протокол зеркала провайдеров разработан таким образом, чтобы его при необходимости можно было реализовать, разместив файлы в обычной службе хостинга статических веб-сайтов. При таком подходе создайте описанные выше ответы с индексами JSON в виде файлов .json в соответствующих вложенных подкаталогах и настройте систему так, чтобы файлы .json отдавались с типом MIME application/json.

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

Подкоманда tofu providers mirror также создаёт файлы index.json и файлы .json для отдельных версий. При размещении в системе хостинга статических веб-сайтов они позволяют формировать ответы, совместимые с протоколом зеркала провайдеров.

Если вы хотите создать зеркало с провайдерами для нескольких конфигураций OpenTofu, запускайте tofu providers mirror по очереди в каждой конфигурации, каждый раз указывая один и тот же выходной каталог. Тогда OpenTofu объединит все требования в единый набор индексов JSON.