Terraform モジュール完全ガイド — 設計から配布・運用まで

「Terraform モジュールの記事が多すぎて、何から読めばいいかわからない」 — NicheeLab には Terraform モジュール関連の専門記事が複数あります。 本記事は、それらを体系的にナビゲートするハブ記事。「モジュールとは何か」から「組織横断で共有モジュールを運用する」までの全フェーズを一望できます。

Terraform モジュールとは何か、なぜ必要か

Terraform モジュールは、再利用可能なインフラ構成を 1 つのコンポーネントとしてカプセル化する仕組みです。 複数の resource ブロック、変数 (variable)、出力 (output) を 1 つのディレクトリにまとめ、他の Terraform コードから呼び出して使います。

モジュール化の最大の価値は、「変更の影響範囲を 1 箇所に閉じ込められる」こと。 例えば、VPC の構成を変えたいときに、3 環境 (dev / staging / prod) の Terraform コードを 3 箇所修正するのではなく、モジュール 1 箇所を変更してバージョンを上げる、という運用が可能になります。

Terraform モジュールの学習パス — 順番に読む記事

Terraform モジュールを体系的にマスターするには、以下の順番で関連記事を読むのが最も効率的です。

1. 入力の設計: Terraformモジュール入力の設計ベストプラクティス — variables の型・デフォルト・validation
2. 出力の設計: モジュール出力を使いこなす — outputs の依存制御と sensitive
3. source の使い分け: Module source の種類 (registry / git / local)
4. バージョニング: Module Versioning 実践 (source と version)
5. 設計パターン: Module 設計パターン (コンポジット・レイヤー・単機能)
6. 合成パターン: 複数モジュールの組合せ実践
7. ベストプラクティス全般: モジュール設計ベストプラクティス
8. 組織横断の運用: 共有モジュール戦略 — Registry / CODEOWNERS / レビュー体制

このリストは、Terraform Associate (003) と Authoring & Operations Professional の両試験のモジュール関連ドメインを完全カバーしています。

試験での出題範囲

Terraform 認定試験におけるモジュール関連の出題比重は以下のとおり。

• Terraform Associate (003): ドメイン 4「Use Terraform modules」が約 15% を占める。Registry の使い方、source の指定、入力出力、バージョン制約が中心
• Authoring & Operations Professional: モジュール設計の判断問題が複数ドメインに分散して出題。共有モジュール戦略、互換性、テスト、組織展開まで含む

Associate 試験では、特に source と version 引数の組み合わせが出題頻度が最も高いトピック。 Professional 試験では、モジュールの公開戦略 (Private Registry / Git Tag / Semantic Versioning) と互換性管理が頻出です。

実務で陥りがちな 5 つの落とし穴

落とし穴 1: モジュール内に環境別の条件分岐を埋め込む

count = var.env == "prod" ? 3 : 1 のように、モジュール内に環境別の if/else を書くと、テストが困難で再利用性が下がります。 環境別の差異は入力変数で吸収し、モジュール自体は環境非依存にするのが原則。

落とし穴 2: 出力を多すぎる、もしくは少なすぎる

全リソースの ID を出力するのは過剰、必要なものだけに絞る。一方、利用側が必要とする出力が抜けていると、利用側でモジュール内の構造を直接参照することになり、カプセル化が崩れます。

落とし穴 3: バージョン固定をしない

source = "..." だけで version 引数を書かないと、最新バージョンが pull され、後方互換破壊で本番が動かなくなる事故が起きます。 必ず version = "~> 1.2" のように範囲指定 or 固定。

落とし穴 4: README / examples を書かない

モジュールの使い方が伝わらないと、利用側が「ソースコード読む or 諦める」の二択になります。 必ず README.md + examples/ ディレクトリで使い方を示す。Terraform Registry に公開する場合は必須。

落とし穴 5: 単一責務を破る

「VPC + EKS + RDS + ALB + Route53 を全部入れる」モジュールは、変更時の影響範囲が広すぎて運用負荷が高い。 単一責務原則に従い、小さなモジュールを組み合わせる方が長期的に保守しやすいです。

代表的なモジュールパターン 3 つ

パターン 1: 単機能モジュール (Atomic)

例: VPC を作成する、RDS を作成する、S3 バケットを作成する。1 つの責務に絞ったモジュールで、再利用性が最も高い。 多くの組織でこのパターンが基本となります。

パターン 2: コンポジットモジュール

例: 「VPC + Subnet + NAT GW + Route Table」のように、関連リソースをまとめる中規模モジュール。 単機能モジュールを内部で呼び出す場合と、すべてフラットに展開する場合がある。

パターン 3: レイヤーモジュール

例: 「ネットワーク層」「データ層」「アプリ層」のように、システム全体を層で分けるモジュール。 大規模システムで採用されるパターンで、State 分離戦略とも密接に関連します。

よくある質問