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

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