Terraform モジュール source の種類を正しく使い分ける: git / registry / local

module ブロックの source は、モジュール取得元を決める唯一の情報源。書式を正しく使い分けないと初期化・更新・固定が破綻します。

本稿は registry / git / local の3形態に絞り、実務の落とし穴と Associate 試験での頻出ポイントに集中します。

モジュール source の基本と解決フロー

module ブロックの source 引数は、Terraform がモジュールをどこから取得するかを決めるアドレスです。代表的な形式は「registry（公開/私有）」「git」「local（相対/絶対パス）」です。terraform init が source を解決し、.terraform/modules 配下に取得・キャッシュします（local は取得せず参照）。

version 引数でモジュールのバージョン制約を指定できるのは registry ソースのみです。git は ?ref= でタグ・ブランチ・コミットを固定、local はリポジトリ管理やリリース手順で固定を担保します。Associate 試験では「どの形式で何を固定できるか」を正確に区別できることが重要です。

• init がモジュールを解決・取得。plan/apply 前に必ず最新の依存関係状態にする
• registry だけが version 引数を受け付ける（SemVer 制約可）。git/local は不可
• .terraform.lock.hcl はプロバイダのロックが中心。module の更新制御は source と init の運用で行う
• git は //subdir と ?ref= の2点が頻出のひっかけ。local は相対パス基準が作業ディレクトリ

モジュール source 解決の流れ（概念図）

Registry ベースの source

公開 Terraform Registry または Terraform Cloud/Enterprise の私有レジストリから取得します。書式は「<ホスト名省略可>/<名前空間>/<モジュール名>/<プロバイダ>」。ホスト名を省略すると registry.terraform.io が既定になります。私有レジストリは app.terraform.io などのホスト名を先頭に付けます。

version 引数で SemVer の制約（~>, >=, = など）が指定できます。terraform init -upgrade で制約範囲内の最新へ更新、無指定の init では既存キャッシュを尊重します。認証は terraform login によるトークン管理が基本です。

• 書式例（公開）: source = "hashicorp/consul/aws"
• 書式例（私有）: source = "app.terraform.io/acme/network/aws"
• version 引数が使えるのは registry のみ（試験頻出）
• init/upgrade の挙動と組み合わせてバージョン固定運用を行う

Git ベースの source

Git リポジトリから取得します。書式は git:: を接頭につけ、HTTPS/SSH いずれも利用可能です。リポジトリ内のサブディレクトリは //path/to/module を末尾に付け、バージョン固定は ?ref=tag|branch|sha で行います。

認証は HTTPS の個人アクセストークンや、SSH のデプロイキー/エージェントを用意します。CI では資格情報を URL に直書きせず、環境変数や認証エージェントを使うのが実務の基本です。

• HTTPS: source = "git::https://github.com/acme/infra-mods.git//modules/vpc?ref=v1.2.0"
• SSH: source = "git::ssh://[email protected]/acme/infra-mods.git//modules/vpc?ref=main"
• version 引数は使えない。固定は ?ref=（タグ/ブランチ/コミット）
• ref 未指定は既定ブランチの最新に追従するため再現性が落ちる（試験の落とし穴）

ローカルパス source

同一リポジトリ内や手元に存在するモジュールを相対/絶対パスで参照します。取得処理はなく、そのまま参照します。相対パスは root module からの相対で解決されます。

変更が即時に反映される一方、バージョン固定の概念はなく、ブランチ運用やリリース工程で再現性を担保します。複数リポジトリ間での再利用には向かないため、その場合は git または registry 化を検討します。

• 相対パス例: source = "./modules/network"
• 親ディレクトリ参照: source = "../shared/vpc"
• init はキャッシュを作らないため、モジュール変更は即反映（ただし plan で差分確認）
• 配布・再利用観点では git/registry への昇格が望ましい

git / registry / local の比較

選択の基準は、再現性の担保と配布容易性です。チームや組織内での安定配布は registry、開発フェーズや内部共有は git、単体リポジトリ内の素早い反復は local が適します。

• 再現性最優先なら registry（version 制約＋ init 運用）
• 中間解として git（?ref= で固定、認証管理に留意）
• 局所最適・試作は local（のちに git/registry 化）

Associate 試験向け要点とサンプル

頻出ポイントは「version が使えるのは registry だけ」「git でサブディレクトリは //、固定は ?ref=」「local は取得せず直接参照」の3本柱です。init と -upgrade の意味、ref 未指定のリスク、私有レジストリのホスト名プレフィックスも押さえましょう。

下記は3形式の最小例です。書式と固定方法の違いを比較してください。

• registry: version 制約での固定と upgrade 運用
• git: //subdir + ?ref= の組み合わせ。version 引数は使えない
• local: パス解決の基準は root module の作業ディレクトリ

3形式の module source 最小例

module "net_registry" {
  source  = "app.terraform.io/acme/network/aws"
  version = "~> 1.2"
  cidr    = "10.0.0.0/16"
}

module "net_git" {
  source = "git::https://github.com/acme/infra-mods.git//modules/network?ref=v1.2.3"
  cidr   = "10.1.0.0/16"
}

module "net_local" {
  source = "./modules/network"
  cidr   = "10.2.0.0/16"
}

問題で確認

よくある質問