プロバイダーレジストリプロトコル

プロバイダーレジストリプロトコルは、OpenTofu CLIがインストール可能なプロバイダーに関するメタデータの検出と、選択したプロバイダーの配布パッケージの場所を特定するために使用されるものです。

このプロトコルの主要な実装は、`registry.opentofu.org`にあるパブリックなOpenTofuレジストリです。このプロトコル独自の実装を作成しデプロイすることで、パブリックなOpenTofuレジストリに公開する代わりに、独自のプロバイダーを配布するための個別の *オリジンレジストリ* を作成できます。

このページでは、インストール可能なプロバイダーを検索するためのプロバイダー *レジストリ* プロトコルについて説明しています。実行時にOpenTofu CLIからの要求を処理するためにプロバイダープラグイン自体が実装するAPIについては説明していません。プロバイダーAPIの詳細については、OpenTofu SDKのドキュメントを参照してください。

プロバイダーアドレス

各OpenTofuプロバイダーには、OpenTofu内で一意に識別される関連付けられたアドレスがあります。プロバイダーアドレスの構文は`hostname/namespace/type`で、

`hostname` は、プロバイダーのオリジンと見なされるレジストリホストであり、CLI設定で上書きされない限り、OpenTofuがプロバイダーに関する情報を参照するデフォルトの場所です。
`namespace` は、特定のホスト名で一意な名前空間の名前であり、何らかの関連性のある1つ以上のプロバイダーを含めることができます。パブリックなOpenTofuレジストリでは、「名前空間」はプロバイダーをパッケージ化および配布している組織を表します。
`type` は、プロバイダーの種類（例：「azurerm」、「aws」、「google」、「dns」など）です。プロバイダーの種類は、特定のホスト名と名前空間内で一意です。

プロバイダーアドレスの`hostname/`部分は（スラッシュ区切り文字を含む）省略可能であり、省略された場合は`registry.opentofu.org/`がデフォルトになります。

例:

`hashicorp/aws` は`registry.opentofu.org/hashicorp/aws`の略で、HashiCorpによって公開された公式のAWSプロバイダーです。
`example/foo` は`registry.opentofu.org/example/foo`の略で、パブリックなOpenTofuレジストリに公開された架空のサードパーティプロバイダーです。
`example.com/bar/baz` は、`example.com`にあるサードパーティプロバイダーレジストリに公開された架空のサードパーティプロバイダーです。

開発したプロバイダーをすべてのOpenTofuユーザーが使用できるように共有する場合は、プロバイダーを検出可能にするパブリックなOpenTofuレジストリに公開することを検討してください。このプロバイダーレジストリプロトコルを実装する必要があるのは、制御下に置かれた異なるホスト名を含むアドレスのプロバイダーを公開する場合のみです。

OpenTofuは、（ホスト名を含めるように常に正規化された後）完全なアドレスを内部的にプロバイダーのグローバル識別子として使用するため、別の名前空間に`examplecorp/azurerm`プロバイダーを再アップロードしたり、異なるホスト名で公開したりすると、OpenTofuはそれを完全に別個のプロバイダーとして認識し、`examplecorp/azurerm`への依存関係を宣言するモジュールでは使用できなくなります。既存のプロバイダーの代替ローカル配布ソース（つまり、プロバイダーの *ミラー*）を作成する目的がある場合は、代わりにプロバイダーインストール方法の設定を参照してください。

プロバイダーバージョン

各個別プロバイダーアドレスには、それぞれバージョン番号が関連付けられた複数のバージョンが関連付けられています。OpenTofuは、バージョン番号がSemantic Versioning 2.0の規則に従っていることを想定しており、エンドユーザーの視点から文書化されたプロバイダーのスキーマと動作がOpenTofuの「パブリックAPI」として機能します。

特定のプロバイダーアドレスのすべての利用可能なバージョンは、OpenTofuによって同じプロバイダーと見なされます。各OpenTofu設定は、構成全体で使用するために各プロバイダーのバージョンを1つだけ選択するため、すべてのモジュール全体のバージョン制約は、バージョン選択の目的でまとめて考慮されます。

サービス検出

プロバイダープロトコルは、OpenTofu CLIがOpenTofuのリモートサービス検出プロトコルを使用して開始し、プロバイダーアドレスのホスト名を「ユーザー向けホスト名」として機能させます。

プロバイダーレジストリプロトコルのサービス識別子は`providers.v1`です。その関連付けられた文字列値は、以下のセクションで定義されている相対URLの基本URLです。

たとえば、プロバイダーレジストリプロトコルのみを実装するホストのサービス検出ドキュメントには、次のものが含まれる場合があります。

コードブロック
{
  "providers.v1": "/tofu/providers/v1/"
}

指定されたURLが相対URLの場合、OpenTofuはそれを検出ドキュメント自体に対する相対URLとして解釈します。特定のプロバイダーレジストリプロトコルエンドポイントは、指定された基本URLを基準とした相対URLとして定義されているため、指定された基本URLは一般的にスラッシュで終わるようにする必要があります。これにより、これらの相対パスが期待どおりに解決されます。

以降のセクションでは、プロバイダーレジストリがOpenTofu CLIのプロバイダーインストーラーと互換性を持たせるために実装する必要があるさまざまな操作について説明します。示されているURLはすべて、上記のようにサービス検出の結果得られたURLを基準とした相対URLです。呼び出し元が仮の`registry.example.io`でサービス検出を既に実行して基本URLを学習していると仮定して、プロバイダーレジストリの仮のURLを使用します。

URL は、コロン:プレフィックスが付いたパス部分は動的に選択される値のプレースホルダーであるという規則に従って表示されます。他のすべてのパス部分はリテラルです。たとえば、:namespace/:type/versionsでは、最初の2つのパス部分はプレースホルダーであり、3番目のパス部分は文字列 "versions" です。

利用可能なバージョン一覧

この操作は、特定のプロバイダーに対して現在利用可能なバージョンを決定します。

メソッド	パス	出力形式
`GET`	`:namespace/:type/versions`	`application/json`

パラメーター

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"}
      ]
    }
  ]
}

レスポンスプロパティ

成功した結果は、versionsという単一のプロパティを含むJSONオブジェクトです。versionsは、それぞれ利用可能なバージョンを記述するオブジェクトの配列であり、以下のプロパティを持ちます。

version（必須）：このオブジェクトが記述するバージョン番号。セマンティックバージョニング文字列表記を使用します。versionは、レスポンス内のすべてのオブジェクト全体で一意である必要があります。
protocols（推奨）：このバージョンがサポートするOpenTofuプロバイダーAPIバージョンの配列。各バージョンはMAJOR.MINOR形式で指定され、各メジャーバージョンは一度だけ表示され、指定されたマイナーバージョンはサポートされている最高のマイナーバージョンです。たとえば、5.1は、プロバイダーがプロトコル5.0とプロトコル5.1の両方をサポートすることを意味します。

OpenTofuは、利用可能な場合、この情報を使用して、現在選択されているバージョンが互換性がない場合、ユーザーが特定のプロバイダーのバージョンをアップグレードまたはダウングレードするためのヒントを提供します。

サポートされるAPIバージョンは、ほとんどのプロバイダーの場合、Terraform SDKのどのバージョンに対してビルドされているかによって決定されます。詳細については、Terraform SDKのドキュメントを参照してください。
platforms（推奨）：このバージョンで利用可能なパッケージを持つプラットフォームを記述するオブジェクトの配列。

OpenTofuは、利用可能な場合、この情報を使用して、ユーザーが現在のプラットフォームとの互換性のために特定のプロバイダーのバージョンをアップグレードまたはダウングレードするためのヒントを提供することがあります。

platformsオブジェクトは、osとarchのプロパティを持ち、その値はプロバイダーパッケージの検索へのレスポンスにおける同名のプロパティと一致します。

レジストリに指定された名前空間とタイプのプロバイダーがないことを示すには、404 Not Foundを返します。

プロバイダーパッケージの検索

この操作は、特定のオペレーティングシステムとアーキテクチャに対するプロバイダーの特定のバージョンの配布パッケージのダウンロードURLと関連メタデータを取得します。

OpenTofu CLIは、構成されたバージョン制約と一致する最新の利用可能なバージョンを選択した後、この操作を使用して、プラグイン自体を含むzipアーカイブを検索します。

メソッド	パス	出力形式
`GET`	`:namespace/:type/:version/download/:os/:arch`	`application/json`

パラメーター

namespace（必須）：要求されたプロバイダーのアドレスのネームスペース部分。
type（必須）：要求されたプロバイダーのアドレスのタイプ部分。
version（必須）：ダウンロードするバージョン。これは、利用可能なバージョン一覧への以前の呼び出しから返されたバージョン文字列の1つと正確に一致します。
os（必須）：返されるパッケージが互換性を持つべきオペレーティングシステムを識別するキーワード（例："linux"または"darwin"）。
arch（必須）：返されるパッケージが互換性を持つべきCPUアーキテクチャを識別するキーワード（例："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（必須）：プロバイダーがサポートするOpenTofuプロバイダーAPIバージョンの配列。利用可能なバージョン一覧と同じ形式です。

利用可能なオプションをリストする際にはオプションですが、OpenTofu CLIが互換性のないパッケージのダウンロードを回避できるように、個々のプロバイダーパッケージを記述するには必須です。
os（必須）：リクエストからのosパラメーターをエコーバックする必要があります。
arch（必須）：リクエストからのarchパラメーターをエコーバックする必要があります。
filename（必須）: "shasums"ドキュメントに記録されているこのプロバイダーのzipアーカイブのファイル名。これにより、OpenTofu CLIはこの特定のパッケージにどのチェックサムを使用すべきかを判断できます。
download_url（必須）：OpenTofuがプロバイダーのzipアーカイブを取得できるURL。これが相対URLの場合、それを含むJSONオブジェクトを返したURLに対して解決されます。
shasums_url（必須）：OpenTofuがこのパッケージと、他のプラットフォーム上の同じプロバイダーバージョンの他のパッケージの予想されるSHA256チェックサムを記録したテキストドキュメントを取得できるURL。

指定されたドキュメントは、多くのUnixシステムで使用可能なsha256コマンドによって生成された形式でなければなりません。1つのエントリがfilenameプロパティで指定されたものと同じファイル名（大文字と小文字を区別）を記録します。
shasums_signature_url（必須）：OpenTofuがshasums_urlのドキュメントのバイナリ、デタッチされたGPG署名（signing_keysプロパティで示されたキーの1つによって署名されたもの）を取得できるURL。
shasum（必須）：shasumsドキュメントに記録されているこのプロバイダーのzipアーカイブのSHA256チェックサム。
signing_keys（必須）：このプロバイダーパッケージの署名キーを記述するオブジェクト。そのうちの1つがshasums_signature_urlの署名の生成に使用されている必要があります。このオブジェクトには、以下のネストされたプロパティがあります。
- gpg_public_keys（必須）：それぞれこのプロバイダーバージョンのチェックサムに署名することを許可された1つのGPG署名キーを記述するオブジェクトの配列。少なくとも1つの要素を含める必要があり、shasums_signature_urlの署名を生成したキーを表します。これらのオブジェクトには、以下のネストされたプロパティがあります。
  - key_id（必須）：このGPGキーの大文字16進数形式のID。
  - ascii_armor（必須）：このGPGキーに関連付けられた公開キーの「ASCIIアーマー」エンコーディング。

要求されたオペレーティングシステムと/またはアーキテクチャでは、指定されたプロバイダーバージョンが利用できないことを示すには、404 Not Foundを返します。OpenTofu CLIは、利用可能なバージョン一覧へのレスポンスで以前に確認したバージョンのみをダウンロードしようとします。

プロバイダーレジストリプロトコル

プロバイダーアドレス​

プロバイダーバージョン​

サービス検出​

利用可能なバージョン一覧​

パラメーター​

サンプルリクエスト​

サンプルレスポンス​

レスポンスプロパティ​

プロバイダーパッケージの検索​

パラメーター​

サンプルリクエスト​

サンプルレスポンス​

レスポンスプロパティ​

プロバイダーアドレス

プロバイダーバージョン

サービス検出

利用可能なバージョン一覧

パラメーター

サンプルリクエスト

サンプルレスポンス

レスポンスプロパティ

プロバイダーパッケージの検索

パラメーター

サンプルリクエスト

サンプルレスポンス

レスポンスプロパティ