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

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 разрешается относительно последнего 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 и отвечает по тому же фиксированному пути обнаружения.

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