Протокол реестра провайдеров

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

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

На этой странице описан протокол реестра провайдеров, предназначенный для поиска провайдеров, доступных для установки. Здесь не описан API, который реализуют сами плагины провайдеров для обработки запросов OpenTofu CLI во время выполнения. Подробнее об API провайдеров см. в документации OpenTofu SDK.

Адреса провайдеров​

Каждому провайдеру OpenTofu соответствует адрес, который однозначно идентифицирует его в OpenTofu. Адрес провайдера имеет синтаксис hostname/namespace/type, где:

• hostname — хост реестра, из которого, как считается, происходит провайдер, а также расположение по умолчанию, к которому OpenTofu будет обращаться за информацией о провайдере, если оно не переопределено в конфигурации CLI.
• namespace — имя пространства имён, уникальное для конкретного имени хоста, в котором может находиться один или несколько связанных между собой провайдеров. В общедоступном реестре OpenTofu «пространство имён» обозначает организацию, которая упаковывает и распространяет провайдер.
• type — тип провайдера, например «azurerm», «aws», «google», «dns» и т. д. Тип провайдера уникален в пределах конкретного имени хоста и пространства имён.

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

Например:

• hashicorp/aws — сокращённая форма адреса registry.opentofu.org/hashicorp/aws, официального провайдера AWS, опубликованного HashiCorp.
• example/foo — сокращённая форма адреса registry.opentofu.org/example/foo, гипотетического стороннего провайдера, опубликованного в общедоступном реестре OpenTofu.
• example.com/bar/baz — гипотетический сторонний провайдер, опубликованный в стороннем реестре провайдеров по адресу example.com.

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

Внутри OpenTofu полный адрес (после нормализации, обеспечивающей наличие имени хоста) используется в качестве глобального идентификатора провайдера. Поэтому важно учитывать, что повторная загрузка провайдера examplecorp/azurerm в другое пространство имён или его публикация на другом имени хоста приведёт к тому, что OpenTofu будет считать его совершенно другим провайдером, который нельзя будет использовать в модулях, объявляющих зависимость от examplecorp/azurerm. Если ваша цель — создать альтернативный локальный источник распространения существующего провайдера, то есть его зеркало, обратитесь к настройке метода установки провайдеров.

Версии провайдеров​

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

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

Обнаружение сервисов​

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

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

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

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

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

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

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

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

Эта операция определяет, какие версии конкретного провайдера доступны в данный момент.

Параметры​

• namespace (обязательный): часть адреса запрошенного провайдера, соответствующая пространству имён.
• type (обязательный): часть адреса запрошенного провайдера, соответствующая типу.

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

curl 'https://registry.opentofu.org/v1/providers/examplecorp/random/versions'

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

{
  "versions": [
    {
      "version": "2.0.0",
      "protocols": ["4.0", "5.1"],
      "platforms": [
        {"os": "darwin", "arch": "amd64"},
        {"os": "linux", "arch": "amd64"},
        {"os": "linux", "arch": "arm"},
        {"os": "windows", "arch": "amd64"}
      ]
    },
    {
      "version": "2.0.1",
      "protocols": ["5.2"],
      "platforms": [
        {"os": "darwin", "arch": "amd64"},
        {"os": "linux", "arch": "amd64"},
        {"os": "linux", "arch": "arm"},
        {"os": "windows", "arch": "amd64"}
      ]
    }
  ]
}

Свойства ответа​

При успешном выполнении возвращается объект JSON, содержащий единственное свойство versions. versions — это массив объектов, каждый из которых описывает одну доступную версию и содержит следующие свойства:

• version (обязательное): номер версии, описываемой этим объектом, в виде строки в формате семантического версионирования. Значение version должно быть уникальным для всех объектов в ответе.

• protocols (рекомендуемое): массив версий API провайдера OpenTofu, поддерживаемых этой версией. Каждая версия указывается в формате MAJOR.MINOR; каждая основная версия встречается только один раз, а указанный дополнительный номер является наибольшим поддерживаемым. Например, 5.1 означает, что провайдер поддерживает как протокол 5.0, так и протокол 5.1.

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

  Для большинства провайдеров поддерживаемые версии API определяются версией Terraform SDK, на основе которой они созданы. Подробнее см. в документации Terraform SDK.

• platforms (рекомендуемое): массив объектов, описывающих платформы, для которых доступны пакеты этой версии.

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

  Объекты platforms имеют свойства os и arch, значения которых соответствуют одноимённым свойствам в ответе на запрос Поиск пакета провайдера.

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

Поиск пакета провайдера​

Эта операция возвращает URL для загрузки дистрибутивного пакета конкретной версии провайдера для заданных операционной системы и архитектуры, а также связанные с пакетом метаданные.

OpenTofu CLI использует эту операцию после выбора самой новой доступной версии, соответствующей настроенным ограничениям версий, чтобы найти ZIP-архив с самим плагином.

Параметры​

• namespace (обязательный): часть адреса запрошенного провайдера, соответствующая пространству имён.
• type (обязательный): часть адреса запрошенного провайдера, соответствующая типу.
• version (обязательный): выбранная для загрузки версия. Она в точности совпадает с одной из строк версии, возвращённых предыдущим вызовом операции Получение списка доступных версий.
• os (обязательный): ключевое слово, обозначающее операционную систему, с которой должен быть совместим возвращаемый пакет, например «linux» или «darwin».
• arch (обязательный): ключевое слово, обозначающее архитектуру процессора, с которой должен быть совместим возвращаемый пакет, например «amd64» или «arm».

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

curl 'https://registry.opentofu.org/v1/providers/examplecorp/random/2.0.0/download/linux/amd64'

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

{
  "protocols": ["4.0", "5.1"],
  "os": "linux",
  "arch": "amd64",
  "filename": "terraform-provider-random_2.0.0_linux_amd64.zip",
  "download_url": "https://releases.example.com/terraform-provider-random/2.0.0/terraform-provider-random_2.0.0_linux_amd64.zip",
  "shasums_url": "https://releases.example.com/terraform-provider-random/2.0.0/terraform-provider-random_2.0.0_SHA256SUMS",
  "shasums_signature_url": "https://releases.example.com/terraform-provider-random/2.0.0/terraform-provider-random_2.0.0_SHA256SUMS.sig",
  "shasum": "5f9c7aa76b7c34d722fc9123208e26b22d60440cb47150dd04733b9b94f4541a",
  "signing_keys": {
    "gpg_public_keys": [
      {
        "key_id": "51852D87348FFC4C",
        "ascii_armor": "-----BEGIN PGP PUBLIC KEY BLOCK-----\nVersion: GnuPG v1\n\nmQENBFMORM0BCADBRyKO1MhCirazOSVwcfTr1xUxjPvfxD3hjUwHtjsOy/bT6p9f\nW2mRPfwnq2JB5As+paL3UGDsSRDnK9KAxQb0NNF4+eVhr/EJ18s3wwXXDMjpIifq\nfIm2WyH3G+aRLTLPIpscUNKDyxFOUbsmgXAmJ46Re1fn8uKxKRHbfa39aeuEYWFA\n3drdL1WoUngvED7f+RnKBK2G6ZEpO+LDovQk19xGjiMTtPJrjMjZJ3QXqPvx5wca\nKSZLr4lMTuoTI/ZXyZy5bD4tShiZz6KcyX27cD70q2iRcEZ0poLKHyEIDAi3TM5k\nSwbbWBFd5RNPOR0qzrb/0p9ksKK48IIfH2FvABEBAAG0K0hhc2hpQ29ycCBTZWN1\ncml0eSA8c2VjdXJpdHlAaGFzaGljb3JwLmNvbT6JATgEEwECACIFAlMORM0CGwMG\nCwkIBwMCBhUIAgkKCwQWAgMBAh4BAheAAAoJEFGFLYc0j/xMyWIIAIPhcVqiQ59n\nJc07gjUX0SWBJAxEG1lKxfzS4Xp+57h2xxTpdotGQ1fZwsihaIqow337YHQI3q0i\nSqV534Ms+j/tU7X8sq11xFJIeEVG8PASRCwmryUwghFKPlHETQ8jJ+Y8+1asRydi\npsP3B/5Mjhqv/uOK+Vy3zAyIpyDOMtIpOVfjSpCplVRdtSTFWBu9Em7j5I2HMn1w\nsJZnJgXKpybpibGiiTtmnFLOwibmprSu04rsnP4ncdC2XRD4wIjoyA+4PKgX3sCO\nklEzKryWYBmLkJOMDdo52LttP3279s7XrkLEE7ia0fXa2c12EQ0f0DQ1tGUvyVEW\nWmJVccm5bq25AQ0EUw5EzQEIANaPUY04/g7AmYkOMjaCZ6iTp9hB5Rsj/4ee/ln9\nwArzRO9+3eejLWh53FoN1rO+su7tiXJA5YAzVy6tuolrqjM8DBztPxdLBbEi4V+j\n2tK0dATdBQBHEh3OJApO2UBtcjaZBT31zrG9K55D+CrcgIVEHAKY8Cb4kLBkb5wM\nskn+DrASKU0BNIV1qRsxfiUdQHZfSqtp004nrql1lbFMLFEuiY8FZrkkQ9qduixo\nmTT6f34/oiY+Jam3zCK7RDN/OjuWheIPGj/Qbx9JuNiwgX6yRj7OE1tjUx6d8g9y\n0H1fmLJbb3WZZbuuGFnK6qrE3bGeY8+AWaJAZ37wpWh1p0cAEQEAAYkBHwQYAQIA\nCQUCUw5EzQIbDAAKCRBRhS2HNI/8TJntCAClU7TOO/X053eKF1jqNW4A1qpxctVc\nz8eTcY8Om5O4f6a/rfxfNFKn9Qyja/OG1xWNobETy7MiMXYjaa8uUx5iFy6kMVaP\n0BXJ59NLZjMARGw6lVTYDTIvzqqqwLxgliSDfSnqUhubGwvykANPO+93BBx89MRG\nunNoYGXtPlhNFrAsB1VR8+EyKLv2HQtGCPSFBhrjuzH3gxGibNDDdFQLxxuJWepJ\nEK1UbTS4ms0NgZ2Uknqn1WRU1Ki7rE4sTy68iZtWpKQXZEJa0IGnuI2sSINGcXCJ\noEIgXTMyCILo34Fa/C6VCm2WBgz9zZO8/rHIiQm1J5zqz0DrDwKBUM9C\n=LYpS\n-----END PGP PUBLIC KEY BLOCK-----",
        "trust_signature": "",
        "source": "ExampleCorp",
        "source_url": "https://www.examplecorp.com/security.html"
      }
    ]
  }
}

Свойства ответа​

При успешном выполнении возвращается объект JSON со следующими свойствами:

• protocols (обязательное): массив версий API провайдера OpenTofu, поддерживаемых провайдером, в том же формате, что и для операции Получение списка доступных версий.

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

• os (обязательное): здесь должно быть возвращено без изменений значение параметра os из запроса.

• arch (обязательное): здесь должно быть возвращено без изменений значение параметра arch из запроса.

• filename (обязательное): имя файла ZIP-архива этого провайдера, указанное в документе «shasums», чтобы OpenTofu CLI мог определить, какую из приведённых контрольных сумм следует использовать для этого пакета.

• download_url (обязательное): URL, по которому OpenTofu может получить ZIP-архив провайдера. Если URL относительный, он будет разрешён относительно URL, с которого был получен содержащий этот объект JSON.

• shasums_url (обязательное): URL, по которому OpenTofu может получить текстовый документ с ожидаемыми контрольными суммами SHA256 для этого пакета и, возможно, других пакетов той же версии провайдера для других платформ.

  Указанный документ должен иметь формат, создаваемый командой sha256, доступной во многих системах Unix, и содержать запись с тем же именем файла, которое указано в свойстве filename (с учётом регистра).

• shasums_signature_url (обязательное): URL, по которому OpenTofu может получить бинарную отсоединённую подпись GPG для документа по адресу shasums_url, подписанную одним из ключей, указанных в свойстве signing_keys.

• shasum (обязательное): контрольная сумма SHA256 ZIP-архива этого провайдера, указанная в документе shasums.

• signing_keys (обязательное): объект с описанием ключей подписи для этого пакета провайдера. Один из этих ключей должен использоваться для подписи по адресу shasums_signature_url. Объект содержит следующие вложенные свойства:

  • gpg_public_keys (обязательное): массив объектов, каждый из которых описывает один ключ подписи GPG, разрешённый для подписания контрольных сумм этой версии провайдера. Необходимо указать хотя бы один элемент — ключ, которым создана подпись по адресу shasums_signature_url. Эти объекты содержат следующие вложенные свойства:

    • key_id (обязательное): идентификатор этого ключа GPG в формате шестнадцатеричного числа в верхнем регистре.

    • ascii_armor (обязательное): представление открытого ключа, связанного с этим ключом GPG, в кодировке «ascii-armor».

Верните 404 Not Found, чтобы сообщить, что указанная версия провайдера недоступна для запрошенной операционной системы и/или архитектуры. OpenTofu CLI будет пытаться загружать только те версии, которые ранее были получены в ответ на запрос Получение списка доступных версий.