Обнаружение удалённых служб

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

Понятное пользователю имя хоста​

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

Протокол обнаружения предназначен для преобразования имени хоста, указанного пользователем, в базовый URL-адрес определённой службы. На каждом хосте могут быть доступны разные наборы служб — или вообще никаких служб! Поэтому у протокола обнаружения есть и второе назначение: позволять OpenTofu определять, какие именно службы доступны для данного имени хоста.

Например, строки источников модулей могут включать имя хоста реестра модулей в качестве первого сегмента, например example.com/namespace/name/provider, а OpenTofu использует обнаружение служб, чтобы определить, есть ли у example.com реестр модулей и, если есть, где доступен его API.

Понятное пользователю имя хоста — это полное интернационализированное доменное имя, представленное в форме Unicode (соответствующая форма «punycode» не допускается). Оно должно разрешаться через DNS в адрес, на котором работает HTTPS-сервер, прослушивающий порт 443.

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

Процесс обнаружения​

Обнаружение начинается с формирования начального URL-адреса обнаружения на основе имени хоста, схемы https: и фиксированного пути /.well-known/terraform.json.

Например, для имени хоста example.com начальным URL-адресом обнаружения будет https://example.com/.well-known/terraform.json.

Затем OpenTofu отправляет запрос GET на этот URL-адрес обнаружения и ожидает ответ в формате JSON. Если код состояния ответа не равен 200, тип содержимого отличается от application/json или тело ответа не удаётся разобрать как объект JSON, обнаружение завершается неудачей, и OpenTofu считает, что хост не поддерживает никаких встроенных служб OpenTofu.

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

Если ответ представляет собой корректный объект JSON, его ключи являются идентификаторами встроенных служб OpenTofu, состоящими из имени типа службы и строки версии, разделённых точкой. Например, идентификатор службы для версии 1 протокола реестра модулей — modules.v1.

Значение каждого элемента объекта — это базовый URL-адрес соответствующей службы. Этот URL-адрес может быть абсолютным или относительным. Если он относительный, то его разрешение выполняется относительно окончательного URL-адреса обнаружения (после перехода по перенаправлениям).

Ниже приведён пример документа обнаружения, объявляющего поддержку версии 1 протокола реестра модулей:

{
  "modules.v1": "https://modules.example.com/v1/"
}

Поддерживаемые службы​

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

• login.v1: протокол входа версии 1
• modules.v1: API реестра модулей версии 1
• providers.v1: API реестра провайдеров версии 1

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

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

Учётные данные также могут передаваться конечным точкам, объявленным в документе обнаружения, в зависимости от требований соответствующей службы.

Нестандартные порты в понятных пользователю именах хостов​

Настоятельно рекомендуется размещать документ обнаружения для имени хоста на стандартном HTTPS-порту 443. Однако в средах разработки это не всегда возможно или удобно, поэтому OpenTofu позволяет добавлять к имени хоста указание порта, состоящее из двоеточия и одной или нескольких десятичных цифр.

Если указан пользовательский номер порта, ожидается, что служба на этом порту будет использовать HTTPS и отвечать по тому же фиксированному пути обнаружения.

Для повседневного использования настоятельно рекомендуется не полагаться на этот механизм, а вместо этого размещать документ обнаружения на стандартном порту, поскольку так можно использовать наиболее удобную для пользователя форму имени хоста.