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

Протокол реестра модулей используется 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, поэтому обычно базовый 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 конечной точки загрузки, образуя URL HTTP-источника модуля.