モジュールレジストリプロトコル
モジュールレジストリプロトコルは、OpenTofu CLIがインストール可能なモジュールに関するメタデータの検出と、選択したモジュールの配布パッケージの場所を特定するために使用します。
このプロトコルの主要な実装は、`registry.opentofu.org`にある公開OpenTofuレジストリです。このプロトコル独自のインプリメンテーションを作成しデプロイすることで、公開OpenTofuレジストリに公開する代わりに、独自のモジュールを配布するための個別のレジストリを作成できます。
モジュールアドレス
各OpenTofuモジュールには、関連付けられたアドレスがあります。モジュールアドレスの構文は`hostname/namespace/name/system`で、
- `hostname`は、このモジュールを提供するモジュールレジストリのホスト名です。
- `namespace`は、特定のホスト名で一意の、何らかの関連性を持つ1つ以上のモジュールを含むことができる名前空間の名前です。公開OpenTofuレジストリでは、「名前空間」はモジュールをパッケージ化および配布している組織を表します。
- `name`はモジュール名で、一般的にモジュールが作成しようとしている抽象化の名前です。
- `system`は、モジュールが主にターゲットとするリモートシステムの名前です。マルチクラウド抽象化の場合、「system」だけが異なるアドレスを持つ複数のモジュールが存在し、プロバイダー固有の実装（例：`registry.opentofu.org/hashicorp/consul/aws`対`registry.opentofu.org/hashicorp/consul/azurerm`）を反映することができます。システム名は、一般的に公式プロバイダーのアドレスのtype部分（上記の例では`aws`または`azurerm`）と一致しますが、これは必須ではなく、組織のレジストリに適したシステムキーワードを使用できます。
モジュールアドレスの`hostname/`部分は（スラッシュデリミタを含む）省略可能であり、省略された場合は`registry.opentofu.org/`がデフォルトになります。
例：
- `hashicorp/consul/aws`は`registry.opentofu.org/hashicorp/consul/aws`の省略形であり、これはAmazon Web ServicesにConsulクラスタをデプロイするための公開レジストリ上のモジュールです。
- `example.com/awesomecorp/consul/happycloud`は、サードパーティのレジストリに公開された仮説上のモジュールです。
すべてのOpenTofuユーザーが使用できるように開発したモジュールを共有する場合は、公開OpenTofuレジストリに公開して、モジュールの検出可能性を高めることを検討してください。独自の制御下にある異なるホスト名を含むモジュールを公開する場合のみ、このモジュールレジストリプロトコルを実装する必要があります。
モジュールバージョン
各々の異なるモジュールアドレスには、それぞれバージョン番号が関連付けられた一連のバージョンが関連付けられています。OpenTofuは、バージョン番号がSemantic Versioning 2.0の規約に従っており、モジュールのユーザー向け動作が「公開API」として機能すると想定しています。
複数のブロックが同じソースアドレスを持っている場合でも、各`module`ブロックはモジュールの異なるバージョンを選択できます。
サービス検出
モジュールレジストリプロトコルは、OpenTofu CLIがモジュールアドレスのホスト名を「ユーザー向けホスト名」として使用するOpenTofuのリモートサービス検出プロトコルから始まります。
モジュールレジストリプロトコルのサービス識別子は`modules.v1`です。関連付けられた文字列値は、以降のセクションで定義されている相対URLのベースURLです。
たとえば、モジュールレジストリプロトコルのみを実装するホストのサービス検出ドキュメントには、次のものが含まれる場合があります。
{
"modules.v1": "/tofu/modules/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/:name/:system/versions | application/json |
パラメーター
-
`namespace` `(文字列: <必須>)` - モジュールの所有者であるユーザーまたは組織。これは必須であり、URLパスの部分として指定されます。
-
`name` `(文字列: <必須>)` - モジュールの名前。これは必須であり、URLパスの部分として指定されます。
-
`system` `(文字列: <必須>)` - ターゲットシステムの名前。これは必須であり、URLパスの部分として指定されます。
サンプルリクエスト
$ curl 'https://registry.opentofu.org/v1/modules/hashicorp/consul/aws/versions'
サンプルレスポンス
レスポンスの`modules`配列には、常に要求されたモジュールが最初の要素として含まれます。
OpenTofuは、このリストの他の要素を使用しません。ただし、サードパーティの実装では、将来の互換性のために常に単一要素のリストを使用する必要があります。
返された各モジュールには利用可能なバージョンの配列が含まれており、OpenTofu はこれを設定で指定されたバージョン制約と照合します。
{
"modules": [
{
"versions": [
{"version": "1.0.0"},
{"version": "1.1.0"},
{"version": "2.0.0"}
]
}
]
}
要求された名前空間、名前、およびターゲットシステムを持つモジュールが存在しないことを示すために、404 Not Found を返します。
特定のモジュールバージョンのソースコードをダウンロードする
このエンドポイントは、単一のターゲットシステムに対して、モジュールの指定されたバージョンをダウンロードします。
| メソッド | パス | 生成 |
|---|---|---|
GET | :namespace/:name/:system/:version/download | application/json |
パラメータ
-
namespace(文字列: <必須>)- モジュールが属するユーザー。必須であり、URLパスの一部として指定されます。 -
`name` `(文字列: <必須>)` - モジュールの名前。これは必須であり、URLパスの部分として指定されます。
-
`system` `(文字列: <必須>)` - ターゲットシステムの名前。これは必須であり、URLパスの部分として指定されます。
-
version(文字列: <必須>)- モジュールのバージョン。必須であり、URLパスの一部として指定されます。
サンプルリクエスト
$ curl -i 'https://registry.opentofu.org/v1/modules/foo/bar/baz/0.0.1/download'
サンプルレスポンス
成功したレスポンスには、モジュールバージョンのソースをダウンロードできる場所が含まれています。
これは、JSON エンコードされた本文のキーlocationの値として含まれることが想定されています。
HTTP/2 200
Content-Length: 81
{"location": "git::https://github.com/foo/terraform-baz-bar?ref=v0.0.1"}
レスポンスボディがない場合、OpenTofu はX-Terraform-Getヘッダーをモジュールの場所として使用します。
HTTP/2 204 No Content
Content-Length: 0
X-Terraform-Get: git::https://github.com/foo/terraform-baz-bar?ref=v0.0.1
レジストリサーバーからボディとX-Terraform-Getヘッダーの両方が受信された場合、OpenTofu はレスポンスボディの内容の読み取りを優先します。
モジュールの場所の値は、モジュールソースで説明されているように、OpenTofu設定のmoduleブロックのsource引数と同じ値を受け入れます。ただし、別のモジュールレジストリアドレスを再帰的に参照することはできません。モジュールの場所の値は、代わりに/、./、または../で始まる相対URLである可能性があり、その場合、ダウンロードエンドポイントの完全なURLを基準にして解決され、HTTP URL モジュールソースが生成されます。