Протокол реестра модулей

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

Основная реализация этого протокола — общедоступный реестр OpenTofu по адресу registry.opentofu.org. Создав и развернув собственную реализацию этого протокола, вы можете создать отдельный реестр для распространения собственных модулей в качестве альтернативы их публикации в общедоступном реестре OpenTofu.

Адреса модулей​

Каждый модуль OpenTofu имеет связанный с ним адрес. Адрес модуля имеет синтаксис hostname/namespace/name/system, где:

• hostname — имя хоста реестра модулей, который предоставляет этот модуль.
• namespace — имя пространства имён, уникальное в пределах определённого имени хоста; оно может содержать один или несколько каким-либо образом связанных модулей. В общедоступном реестре OpenTofu «пространство имён» обозначает организацию, которая упаковывает и распространяет модуль.
• name — имя модуля, которое обычно обозначает абстракцию, создаваемую модулем.
• system — имя удалённой системы, для работы с которой в первую очередь предназначен модуль. Для абстракций, охватывающих несколько облачных платформ, могут существовать модули, адреса которых различаются только значением «системы», отражая реализации абстракции для конкретных провайдеров, например registry.opentofu.org/hashicorp/consul/aws и registry.opentofu.org/hashicorp/consul/azurerm. Имя системы обычно совпадает с частью типа в адресе официального провайдера, например aws или azurerm в приведённых выше примерах, однако это необязательно: вы можете выбрать любые ключевые слова системы, подходящие для организации вашего реестра.

Часть hostname/ адреса модуля (включая разделитель в виде косой черты) является необязательной; если её не указать, по умолчанию используется registry.opentofu.org/.

Например:

• hashicorp/consul/aws — это сокращённая форма registry.opentofu.org/hashicorp/consul/aws, модуля из общедоступного реестра для развёртывания кластеров Consul в Amazon Web Services.
• example.com/awesomecorp/consul/happycloud — гипотетический модуль, опубликованный в стороннем реестре.

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

Версии модулей​

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

Каждый блок module может выбирать отдельную версию модуля, даже если у нескольких блоков указан один и тот же исходный адрес.

Обнаружение служб​

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

Идентификатор службы для протокола реестра модулей — modules.v1. Связанное с ним строковое значение — базовый URL для относительных URL, определённых в следующих разделах.

Например, документ обнаружения службы для хоста, который реализует только протокол реестра модулей, может содержать следующее:

{
  "modules.v1": "/tofu/modules/v1/"
}

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

В следующих разделах описаны различные операции, которые должен реализовать реестр модулей для совместимости с установщиком модулей CLI OpenTofu. Все указанные URL относительны URL, полученному в результате обнаружения службы, как описано выше. Мы используем гипотетический URL для реестра провайдеров, предполагая, что вызывающая сторона уже выполнила обнаружение службы для гипотетического registry.example.io и узнала базовый URL.

В URL используется соглашение, согласно которому часть пути с префиксом двоеточия : обозначает заполнитель для динамически выбираемого значения, а все остальные части пути являются буквальными. Например, в :namespace/:type/versions первые две части пути являются заполнителями, а третья — буквальной строкой «versions».

Получение списка доступных версий определённого модуля​

Это основная конечная точка для определения источников модулей; она возвращает доступные версии указанного модуля с полным именем.

Параметры​

• namespace (string: <required>) — пользователь или организация, которым принадлежит модуль. Это обязательный параметр, указываемый в пути URL.

• name (string: <required>) — имя модуля. Это обязательный параметр, указываемый в пути URL.

• system (string: <required>) — имя целевой системы. Это обязательный параметр, указываемый в пути URL.

Пример запроса​

$ curl 'https://registry.opentofu.org/v1/modules/hashicorp/consul/aws/versions'

Пример ответа​

Массив modules в ответе всегда содержит запрошенный модуль первым элементом.

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

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

{
   "modules": [
      {
         "versions": [
            {"version": "1.0.0"},
            {"version": "1.1.0"},
            {"version": "2.0.0"}
         ]
      }
   ]
}

Возвращайте 404 Not Found, чтобы указать, что модуль с запрошенными пространством имён, именем и целевой системой недоступен.

Загрузка исходного кода определённой версии модуля​

Эта конечная точка загружает указанную версию модуля для одной целевой системы.

Параметры​

• namespace (string: <required>) — пользователь, которому принадлежит модуль. Это обязательный параметр, указываемый в пути URL.

• name (string: <required>) — имя модуля. Это обязательный параметр, указываемый в пути URL.

• system (string: <required>) — имя целевой системы. Это обязательный параметр, указываемый в пути URL.

• version (string: <required>) — версия модуля. Это обязательный параметр, указываемый в пути URL.

Пример запроса​

$ curl -i 'https://registry.opentofu.org/v1/modules/foo/bar/baz/0.0.1/download'

Пример ответа​

Успешный ответ содержит местоположение, откуда можно загрузить исходный код версии модуля.

Ожидается, что оно будет указано в теле ответа в формате JSON как значение ключа location:

HTTP/2 200
Content-Length: 81

{"location": "git::https://github.com/foo/terraform-baz-bar?ref=v0.0.1"}

Если тело ответа отсутствует, OpenTofu использует заголовок X-Terraform-Get в качестве местоположения модуля:

HTTP/2 204 No Content
Content-Length: 0
X-Terraform-Get: git::https://github.com/foo/terraform-baz-bar?ref=v0.0.1

В качестве значения местоположения модуля можно использовать те же значения, что и для аргумента source в блоке module конфигурации OpenTofu, как описано в разделе Источники модулей, за исключением того, что оно не может рекурсивно ссылаться на другой адрес реестра модулей. Вместо этого в качестве значения местоположения модуля может использоваться относительный URL, начинающийся с /, ./ или ../. В этом случае он разрешается относительно полного URL конечной точки загрузки, в результате чего получается HTTP-адрес источника модуля.