本文へスキップ

標準モジュール構造

標準モジュール構造とは、別々のリポジトリに配布される再利用可能なモジュールに推奨するファイルとディレクトリのレイアウトです。OpenTofuツールは標準モジュール構造を理解するように構築されており、この構造を使用してドキュメントを生成し、モジュールレジストリにモジュールをインデックス登録するなどを行います。

標準モジュール構造では、以下に記載されているレイアウトが想定されています。項目数は多いように見えますが、ルートモジュール以外はすべてオプションです。ほとんどのモジュールは、標準構造に従うために追加作業を行う必要はありません。

  • ルートモジュール。これは、標準モジュール構造で唯一必須の要素です。OpenTofuファイルは、リポジトリのルートディレクトリに存在する必要があります。これはモジュールの主要なエントリポイントであり、独自の意見を持つことが期待されます。Consulモジュールでは、ルートモジュールによって完全なConsulクラスタが設定されます。ただし、多くの前提条件が含まれており、高度なユーザーは特定のネストされたモジュールを使用して、より慎重に制御することを期待しています。

  • README。ルートモジュールとネストされたモジュールには、READMEファイルが必要です。このファイルの名前はREADMEまたはREADME.mdにする必要があります。後者はマークダウンとして扱われます。モジュールとその使用方法に関する説明を記述する必要があります。このモジュールを他のリソースと組み合わせて使用する方法の例を含めたい場合は、このようなexamplesディレクトリに配置します。モジュールが作成するインフラストラクチャリソースとその関係を示す図を含めることを検討してください。

    READMEでは、ツールの自動生成によりモジュールの入力や出力を文書化する必要はありません。リポジトリ自体に含まれるファイルへのリンクまたは画像の埋め込みを行う場合は、コミット固有の絶対URLを使用してください。そうすることで、将来、リソースの誤ったバージョンを指すことがなくなります。

  • LICENSE。このモジュールが利用可能なライセンス。モジュールを公開する場合、多くの組織は明確なライセンスがない限り、モジュールを採用しません。オープンソースライセンスでない場合でも、常にライセンスファイルを用意することをお勧めします。

  • main.tf、variables.tf、outputs.tf。空であっても、最小限のモジュールにはこれらのファイル名が推奨されます。main.tfは主要なエントリポイントにする必要があります。単純なモジュールの場合、これはすべてのリソースが作成される場所です。複雑なモジュールの場合は、リソースの作成を複数のファイルに分割できますが、ネストされたモジュール呼び出しはメインファイル内にある必要があります。variables.tfとoutputs.tfには、それぞれ変数と出力の宣言を含める必要があります。

  • 変数と出力には説明が必要です。すべての変数と出力には、目的を説明する1〜2文の説明が必要です。これはドキュメント作成に使用されます。変数の構成と出力の構成に関するドキュメントで詳細を確認してください。

  • ネストされたモジュール。ネストされたモジュールは、modules/サブディレクトリに存在する必要があります。README.mdを持つネストされたモジュールは、外部ユーザーが使用可能と見なされます。READMEが存在しない場合は、内部使用のみと見なされます。これらは純粋に助言的なものであり、OpenTofuは内部モジュールの使用を積極的に拒否しません。ネストされたモジュールは、高度なユーザーが慎重に選択して使用できる、複数の小さなモジュールに複雑な動作を分割するために使用する必要があります。たとえば、Consulモジュールには、必要なIAMポリシーを設定するためのモジュールとは別に、クラスタを作成するためのネストされたモジュールがあります。これにより、ユーザーは独自のIAMポリシーを選択できます。

    ルートモジュールにネストされたモジュールへの呼び出しが含まれている場合、./modules/consul-clusterのような相対パスを使用する必要があります。そうすることで、OpenTofuはそれらを同じリポジトリまたはパッケージの一部と見なし、個別に再度ダウンロードすることはありません。

    リポジトリまたはパッケージに複数のネストされたモジュールが含まれている場合、理想的には、互いに直接呼び出してモジュールの深くネストされたツリーを作成するのではなく、呼び出し元によって構成可能である必要があります。

  • 例。モジュールの使用例は、リポジトリのルートにあるexamples/サブディレクトリに存在する必要があります。各例には、例的目标と使用方法を説明するREADMEを含めることができます。サブモジュールの例も、ルートのexamples/ディレクトリに配置する必要があります。

    例は多くの場合、カスタマイズのために他のリポジトリにコピーされるため、すべてのmoduleブロックのsourceは、相対パスではなく、外部呼び出し元が使用するアドレスに設定する必要があります。

標準構造に従う最小限に推奨されるモジュールを以下に示します。ルートモジュールは唯一の必須要素ですが、以下に示す構造を最小限のものとして推奨します。

コードブロック
$ tree minimal-module/
.
├── README.md
├── main.tf
├── variables.tf
├── outputs.tf

標準構造に従うモジュールの完全な例を以下に示します。この例にはすべてのオプション要素が含まれているため、モジュールが持つことができる最も複雑な例です。

コードブロック
$ tree complete-module/
.
├── README.md
├── main.tf
├── variables.tf
├── outputs.tf
├── ...
├── modules/
│   ├── nestedA/
│   │   ├── README.md
│   │   ├── variables.tf
│   │   ├── main.tf
│   │   ├── outputs.tf
│   ├── nestedB/
│   ├── .../
├── examples/
│   ├── exampleA/
│   │   ├── main.tf
│   ├── exampleB/
│   ├── .../