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

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

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. Следовательно, при желании по этому 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.