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

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

Основная реализация этого протокола — общедоступный реестр 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 предполагает, что номера версий соответствуют соглашениям Semantic Versioning 2.0, а поведение модуля, доступное пользователю, служит его «публичным API».

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

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

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

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

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

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

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

В следующих разделах описаны различные операции, которые должен реализовать реестр модулей для совместимости с программой установки модулей OpenTofu CLI. Все указанные 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 URL.