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

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