プロバイダーネットワークミラープロトコル
プロバイダーネットワークミラープロトコルは、オプションのプロトコルです。これを実装することで、元のレジストリに関係なく、Terraformプロバイダーの代替インストールソースを提供できます。
OpenTofuは、CLI設定の`provider_installation`ブロックで明示的に有効にした場合のみ、ネットワークミラーを使用します。有効にすると、ネットワークミラーは任意のレジストリホスト名に属するプロバイダーを提供できます。これにより、組織は、各プロバイダーの元のレジストリではなく、内部サーバーから使用するすべてのOpenTofuプロバイダーを提供できます。
これは、OpenTofuプロバイダーの元のレジストリとして機能しようとするホストが実装すべきプロトコルではありません。元のレジストリ（そのホスト名が、ホストするプロバイダーのソースアドレスに含まれます）を提供するには、代わりにプロバイダーレジストリプロトコルを実装してください。
プロバイダーアドレス
各OpenTofuプロバイダーには、OpenTofu内で一意に識別する関連付けられたアドレスがあります。プロバイダーアドレスの構文は`hostname/namespace/type`であり、プロバイダー要件ドキュメントで詳しく説明されています。
デフォルトでは、プロバイダーアドレスの`hostname`部分は、一意の識別子の一部と、そこから取得するレジストリの場所の両方の役割を果たします。ただし、ネットワークミラーからプロバイダーをインストールするようにOpenTofuを設定すると、`hostname`は識別子としてのみ機能し、インストールソースとしては機能しなくなります。したがって、プロバイダーミラーは、`registry.opentofu.org`にあるパブリックOpenTofuレジストリからのプロバイダーを含む、さまざまなプロバイダーレジストリホスト名に属するプロバイダーを単一のサーバーから提供できます。
このドキュメントの後の相対URLパターンでは、プレースホルダー`：hostname`は、要求されているプロバイダーのアドレスのホスト名を指し、プロバイダーネットワークミラーが展開されているホスト名ではありません。
プロトコルベースURL
ほとんどのOpenTofuネイティブサービスは、リモートサービス検出プロトコルを使用しているため、エンドポイントの物理的な場所は、識別子で使用されるホスト名から分離される可能性があります。プロバイダーネットワークミラープロトコルは、サービス検出のインダイレクションを使用しません。これは、ネットワークミラーの場所は物理的な場所のみであり、OpenTofu設定の依存関係の識別子の一部として決して使用されないためです。
代わりに、CLI設定のプロバイダーインストールセクションは、ベースURLを直接受け入れます。指定されたURLは、スキーム`https：`を使用する必要があり、個々の操作エンドポイントの相対URLがその下に解決されるように、末尾にスラッシュを付ける必要があります。
provider_installation {
network_mirror {
url = "https://tofu.example.com/providers/"
}
}
OpenTofuは、操作エンドポイントのURLを解決するためのステムとしてベースURLのみを使用するため、ベースURLに直接アクセスすることはありません。したがって、必要に応じて、そのURLにネットワークミラーの使いやすさを説明したドキュメントを公開できます。
次のセクションでは、プロバイダーネットワークミラーサーバーがOpenTofu CLIのプロバイダーインストーラーと互換性を持つために実装する必要があるさまざまな操作について説明します。示されているURLはすべて、上記で説明したように、指定されたベースURLを基準とした相対URLです。
URLは、コロン`：`プレフィックスが付いたパス部分は動的に選択された値のプレースホルダーであり、その他のパス部分はリテラルであるという規則で示されています。たとえば、`:hostname/:namespace/:type/index.json`では、最初の3つのパス部分はプレースホルダーであり、3番目のパス部分は文字列「index.json」です。
以降のセクションの例のリクエストは、上記のCLI設定例からの例となるミラーベースURLを想定しています。
認証
CLI設定に、ネットワークミラーベースURLで指定されたホスト名の認証情報が含まれている場合、OpenTofuは、以下に説明する操作のリクエストにこれらの認証情報を含めます。
指定されたURLが標準以外のポート番号（443以外）を使用する場合、認証情報は、`tofu.example.com:8443`など、ポート番号を含むホスト名に関連付ける必要があります。
OpenTofuは、以下で説明する「使用可能なインストールパッケージの一覧」レスポンスで指定されたURLのアーカイブを取得する際には、認証情報を送信しません。特定のミラーが配布パッケージ自体を機密情報と見なす場合、メタデータレスポンスには、暗号化的に安全で、ユーザー固有で、時間制限のあるURLを使用する必要があります。そうするための戦略は、このプロトコルドキュメントの範囲外です。
使用可能なバージョンのリスト
この操作は、特定のプロバイダーで現在使用可能なバージョンを決定します。
| メソッド | パス | 生成 |
|---|---|---|
GET | :hostname/:namespace/:type/index.json | application/json |
パラメーター
- `hostname`（必須）：要求されたプロバイダーのアドレスのホスト名部分。
- `namespace`（必須）：要求されたプロバイダーのアドレスの名前空間部分。
- `type`（必須）：要求されたプロバイダーのアドレスのタイプ部分。
サンプルリクエスト
curl 'https://tofu.example.com/providers/registry.tofu.io/hashicorp/random/index.json'
サンプルレスポンス
{
"versions": {
"2.0.0": {},
"2.0.1": {}
}
}
レスポンスプロパティ
成功した結果は、`versions`という単一のプロパティを含むJSONオブジェクトです。これはJSONオブジェクトである必要があります。
versionsオブジェクトのプロパティ名は、利用可能なバージョン番号を表します。プロパティの値はオブジェクトでなければなりませんが、それらのオブジェクトにはプロパティは定義されていません。将来の互換性のために、これらのオブジェクトは空のままにしておくことをお勧めします。
ミラーに指定されたアドレスのプロバイダーがないことを示すために、404 Not Foundを返します。
利用可能なインストールパッケージの一覧
この操作は、特定のバージョンのプロバイダーの配布パッケージのダウンロードURLと関連メタデータを取得します。
各配布パッケージは、特定のオペレーティングシステムとアーキテクチャに関連付けられています。ネットワークミラーは、ミラーのユーザーがOpenTofuがサポートするターゲットプラットフォームのサブセットのみを使用することがわかっている場合、プロバイダーバージョンの利用可能なパッケージのサブセットのみをホストすることがあります。
OpenTofu CLIは、設定されたバージョン制約に一致する最新の利用可能なバージョンを選択した後、この操作を使用して、プラグイン自体を含むzipアーカイブを見つけます。
| メソッド | パス | 生成 |
|---|---|---|
GET | :hostname/:namespace/:type/:version.json | application/json |
パラメーター
- `hostname`（必須）：要求されたプロバイダーのアドレスのホスト名部分。
- `namespace`（必須）：要求されたプロバイダーのアドレスの名前空間部分。
- `type`（必須）：要求されたプロバイダーのアドレスのタイプ部分。
version（必須）：ダウンロードするバージョンを選択します。これは、利用可能なバージョンのリストへの以前の呼び出しから返されたバージョン文字列のいずれかと完全に一致する必要があります。
サンプルリクエスト
curl 'https://tofu.example.com/providers/registry.tofu.io/hashicorp/random/2.0.0.json'
サンプルレスポンス
{
"archives": {
"darwin_amd64": {
"url": "terraform-provider-random_2.0.0_darwin_amd64.zip",
"hashes": [
"h1:4A07+ZFc2wgJwo8YNlQpr1rVlgUDlxXHhPJciaPY5gs="
]
},
"linux_amd64": {
"url": "terraform-provider-random_2.0.0_linux_amd64.zip",
"hashes": [
"h1:lCJCxf/LIowc2IGS9TPjWDyXY4nOmdGdfcwwDQCOURQ="
]
}
}
}
レスポンスプロパティ
成功した結果は、archivesというプロパティを持つJSONオブジェクトです。これはJSONオブジェクトでなければなりません。
archivesオブジェクトのプロパティ名はそれぞれ、オペレーティングシステムとアーキテクチャをアンダースコア（_）で連結したターゲットプラットフォーム識別子です。
archivesオブジェクトの各プロパティ値は、それ自体が次のプロパティを持つ入れ子になったオブジェクトです。
-
url（必須）：OpenTofuが要求されたプロバイダープラグインバージョンを含む.zipアーカイブをダウンロードするURLを指定する文字列。OpenTofuは、現在のJSONドキュメントが返されたURLに対して相対的にURLを解決するため、ファイル名のみを含む上記の例では、OpenTofuは次のようなURLを構築します。
コードブロック https://tofu.example.com/providers/registry.opentofu.org/hashicorp/random/terraform-provider-random_2.0.0_darwin_amd64.zip -
hashes（オプション）：示されたアーカイブの1つ以上のハッシュ値を含む文字列のJSON配列。これらのハッシュは、OpenTofuのプロバイダーパッケージハッシュアルゴリズムを使用します。現時点では、これらを設定する最も簡単な方法は、後続のセクションで説明されているように、tofu providers mirrorコマンドを使用してミラーのJSONインデックスを構築することです。これには、各プロバイダーの計算されたハッシュが含まれます。レスポンスに少なくとも1つのハッシュが含まれている場合、OpenTofuはアルゴリズムが最も強力であると見なすハッシュを選択し、ダウンロードされたパッケージがそのハッシュと一致することを確認します。レスポンスに
hashesプロパティが含まれていない場合、OpenTofuは検証なしで指定されたアーカイブをインストールします。
OpenTofu CLIは、利用可能なバージョンのリストへの応答で以前に確認済みのバージョンのみをダウンロードしようとします。
静的ウェブサイトとしてのプロバイダーミラー
プロバイダーミラープロトコルは、一般的な静的ウェブサイトホスティングサービスにファイル配置することで実装できる可能性があるように設計されています。この戦略を使用する場合は、上記で説明したJSONインデックスレスポンスを適切な入れ子になったサブディレクトリ内の.jsonファイルとして実装し、システムがapplication/jsonメディアタイプで.jsonファイルをサービスするように設定されていることを確認してください。
便宜上、OpenTofu CLIにはtofu providers mirrorサブコマンドが含まれており、これは必要なプロバイダーの現在の構成を分析し、それらのプロバイダーのパッケージを元のレジストリからダウンロードし、ミラーとして使用できるローカルディレクトリに配置します。
tofu providers mirrorサブコマンドは、静的ウェブサイトホスティングシステムに配置された場合、プロバイダーミラープロトコルと互換性のあるレスポンスを生成できるindex.jsonとバージョン固有の.jsonファイルも生成します。
複数の異なるOpenTofu構成のプロバイダーを含むミラーを作成する場合は、毎回同じ出力ディレクトリを提供しながら、各構成で順番にtofu providers mirrorを実行します。OpenTofuは、すべての要件を単一のJSONインデックスセットにマージします。