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

Протокол реестра провайдеров используется 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"
      }
    ]
  },
  "packages": {
    "darwin_amd64": {
      "hashes": [
        "zh:fa36a9bfe2f1532af36af30ab607f2858aef6ae73754349123fe140f9bef0701",
        "h1:yZ6W9xVRg/J+CsYC5zefHGnaygOxVVCk34uidFslHV4="
      ],
      "package_size": 6555985
    },
    "darwin_arm64": {
      "hashes": [
        "zh:b4798fb4b1171ee66435212dc633c1836ed38314566c67a2a29d2d426b020a77",
        "h1:Q1NTszPWmiltpevj7SqfEL3GnYby/13i4oKGEWkJCKM="
      ],
      "package_size": 6184593
    }
  }
}

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

Успешный ответ — это объект 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.

• packages (рекомендуемое): метаданные пакета для конкретной платформы, помогающие при фиксации версий провайдера.

  • hashes (обязательное): список допустимых хешей для конкретного пакета провайдера.

  • package_size (обязательное): размер конкретного пакета провайдера в байтах. Используется для защиты от атак с коллизиями хешей.

    Если указано packages, необходимо включить сведения для всех платформ независимо от того, для какой платформы был сделан запрос, поскольку приведённые контрольные суммы обычно копируются в файл блокировки зависимостей для проверки пакетов, устанавливаемых на других платформах в будущем. Для каждой платформы необходимо указать как минимум хеш zh:, соответствующий значению, которое будет возвращено в свойстве верхнего уровня shasum при запросе для этой платформы.

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