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

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

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