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

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

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