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

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

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 (обязательное): кодировка «ascii-armor» для открытого ключа, связанного с этим ключом GPG.

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