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

Протокол сетевого зеркала провайдеров — это необязательный протокол, который можно реализовать, чтобы предоставить альтернативный источник установки провайдеров 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. Поэтому при желании по этому 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 с типом медиа application/json.

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

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

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