本文へ移動

モジュールブロック

モジュールは、まとめて使用される複数のリソースを格納するコンテナです。

すべてのOpenTofu構成には、少なくとも1つのモジュール（ルートモジュール）があり、これはメイン作業ディレクトリの.tfファイルと.tofuファイルで定義されたリソースで構成されます。

モジュールは他のモジュールを呼び出すことができ、これにより、子モジュールのリソースを簡潔な方法で構成に含めることができます。モジュールは、同じ構成内または別の構成内で複数回呼び出すこともでき、リソース構成をパッケージ化して再利用できます。

このページでは、あるモジュールから別のモジュールを呼び出す方法について説明します。再利用可能な子モジュールの作成の詳細については、モジュール開発を参照してください。

子モジュールの呼び出し​

モジュールを呼び出すとは、そのモジュールの内容を、入力変数に特定の値を指定して構成に含めることを意味します。モジュールは、他のモジュール内からmoduleブロックを使用して呼び出されます。

コードブロック
module "servers" {
  source = "./app-cluster"

  servers = 5
}

このようなmoduleブロックを含むモジュールは、子モジュールの呼び出しモジュールです。

moduleキーワードの直後のラベルはローカル名であり、呼び出しモジュールはこのモジュールのインスタンスを参照するために使用できます。

ブロック本体（{と}の間）には、モジュールの引数が含まれます。モジュールの呼び出しでは、次の種類の引数を使用します。

  • source引数は、すべてのモジュールで必須です。

  • version引数は、レジストリのモジュールにお勧めです。

  • 他のほとんどの引数は、モジュールによって定義された入力変数に対応します。（上記の例では、servers引数はその1つです。）

  • OpenTofuは、for_eachやdepends_onなど、すべてのモジュールで使用できるいくつかの他のメタ引数を定義しています。

ソース​

すべてのモジュールは、OpenTofuによって定義されたメタ引数であるsource引数を**必須**とします。その値は、モジュールの構成ファイルを含むローカルディレクトリのパス、またはOpenTofuがダウンロードして使用するリモートモジュールソースのいずれかです。この引数の可能な値の詳細については、モジュールソースを参照してください。

同じソースアドレスを複数のmoduleブロックで指定して、定義されたリソースの複数のコピーを作成できます（変数の値は異なる場合があります）。

moduleブロックを追加、削除、または変更した後、tofu initを再実行して、OpenTofuがインストールされたモジュールを調整できるようにする必要があります。デフォルトでは、このコマンドは既にインストールされているモジュールをアップグレードしません。最新バージョンにアップグレードするには、-upgradeオプションを使用します。

バージョン​

モジュールレジストリからインストールされたモジュールを使用する場合、予期しない変更や望ましくない変更を避けるために、許容されるバージョン番号を明示的に制約することをお勧めします。

moduleブロックでversion引数を使用してバージョンを指定します。

コードブロック
module "consul" {
  source  = "hashicorp/consul/aws"
  version = "0.0.5"

  servers = 3
}

version引数は、バージョン制約文字列を受け入れます。OpenTofuは、制約を満たすモジュールの最新インストール済みバージョンを使用します。適切なバージョンがインストールされていない場合は、制約を満たす最新バージョンをダウンロードします。

バージョン制約は、公開OpenTofuレジストリやTACOS（TF Automation and Collaboration Software）プライベートモジュールレジストリなど、モジュールレジストリからインストールされたモジュールでのみサポートされています。他のモジュールソースは、ソース文字列自体内に独自のバージョン管理メカニズムを提供するか、まったくバージョンをサポートしない場合があります。特に、ローカルファイルパスからソースされたモジュールはversionをサポートしません。同じソースリポジトリからロードされるため、常に呼び出し元と同じバージョンを共有します。

メタ引数​

sourceとversionに加えて、OpenTofuは、すべてのモジュールで特別な意味を持ついくつかのオプションのメタ引数を定義しており、次のページで詳しく説明しています。

  • count - 1つのmoduleブロックからモジュールの複数のインスタンスを作成します。countページで詳細を参照してください。

  • for_each - 1つのmoduleブロックからモジュールの複数のインスタンスを作成します。for_eachページで詳細を参照してください。

  • providers - プロバイダー構成を子モジュールに渡します。providersページで詳細を参照してください。指定しない場合、子モジュールは呼び出しモジュールからすべてのデフォルト（エイリアスなし）のプロバイダー構成を継承します。

  • depends_on - モジュール全体とリストされたターゲット間に明示的な依存関係を作成します。depends_onページで詳細を参照してください。

OpenTofuはlifecycle引数を使用しません。ただし、lifecycleブロックは将来のバージョン用に予約されています。

モジュール出力値へのアクセス​

モジュールで定義されたリソースはカプセル化されているため、呼び出し元モジュールはそれらの属性に直接アクセスできません。ただし、子モジュールは出力値を宣言して、特定の値を選択的にエクスポートし、呼び出し元モジュールからアクセスできるようにすることができます。

たとえば、上記の例で参照されている./app-clusterモジュールがinstance_idsという名前の出力値をエクスポートした場合、呼び出し元モジュールはmodule.servers.instance_idsという式を使用してその結果を参照できます。

コードブロック
resource "aws_elb" "example" {
  # ...

  instances = module.servers.instance_ids
}

名前付き値の参照の詳細については、式を参照してください。

リソース状態のモジュールへの移行​

resourceブロックを1つのモジュールから複数の子モジュールに移動すると、OpenTofuは新しい場所を完全に異なるリソースとして認識します。その結果、OpenTofuは古いアドレスにあるすべてのリソースインスタンスを破棄し、新しいアドレスに新しいインスタンスを作成する予定です。

既存のオブジェクトを保持するには、リファクタリングブロックを使用して、各リソースインスタンスの古いアドレスと新しいアドレスを記録できます。これにより、OpenTofuは古いアドレスにある既存のオブジェクトを、対応する新しいアドレスで元々作成されたかのように扱います。

モジュール内でのリソースの置換​

特定の仮想マシンが劣化している基盤ハードウェア上で実行されている場合など、OpenTofuに自動的に認識されない理由で、オブジェクトを新しいオブジェクトに置き換える必要がある場合があります。この場合、-replace=...プランニングオプションを使用して、OpenTofuがそのオブジェクトの置換を提案するように強制できます。

オブジェクトがネストされたモジュール内のリソースに属している場合は、それに至るすべてのネストされたモジュールステップを含む、そのリソースへの完全なパスを指定します。例：

コードブロック
$ tofu plan -replace=module.example.aws_instance.example

上記は、ルートモジュール内で宣言されたmodule "example"子モジュール内に宣言されたresource "aws_instance" "example"を選択します。

置換は非常に破壊的なアクションであるため、OpenTofuでは個々のリソースインスタンスのみを選択できます。特定のモジュールに属するすべてのリソースインスタンスの置換を強制する構文はありません。