Terraform Private Modules: 組織内モジュール運用の実務指針

公共のTerraform Registryを使わず、組織内だけでモジュールを安全に配布したい。そんな要件に対して最も安定した解は、Terraform Cloud/EnterpriseのPrivate Module Registry（PMR）です。

本稿ではPMRの全体像、命名とSemVer運用、発行と消費のフロー、権限・可視性、テスト戦略、移行・トラブルの勘所をまとめます。Terraformの出題傾向（レジストリ参照 vs Git参照、version制約の扱い）も要点化しています。

全体像と選択肢：なぜプライベートモジュールか

Private Module Registryは、VCSリポジトリのタグをセマンティックバージョンとして取り込み、組織内ユーザーに名前解決と配布を提供します。Terraform CLIはレジストリから解決されるソースアドレスを優先的に扱い、version引数での制約も解釈できます。

Gitの生URL参照（git::）でも配布は可能ですが、検索性・バージョン選択・アクセス制御・監査の観点でPMRが有利です。自社ホストのRegistry API実装は高度ですが、まずはTerraform Cloud/Enterpriseを使うのが現実的です。

• 安定運用の要は「命名規約 + セマンティックバージョニング + 自動テスト + 最小権限」。
• レジストリ参照では module ブロックの version が効く。Git参照では効かず、ref= で固定する必要がある。
• 組織スケールではモジュールの発見性（検索・ドキュメント化）が生産性を左右する。

PMRベースの配布フロー（概念図）

レジストリ参照の最小例（version制約つき）

module "vpc" {
  source  = "app.terraform.io/acme/vpc/aws"
  version = "~> 1.2"

  name    = "core"
  cidr    = "10.0.0.0/16"
}

terraform {
  required_version = ">= 1.4"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

命名規約とセマンティックバージョニング運用

PMRは、リポジトリ命名とタグを手がかりにモジュールを認識します。命名は terraform-<provider>-<name>（例: terraform-aws-vpc）が基本です。タグはセマンティックバージョンと整合している必要があります。

タグの表記は v1.2.3 を推奨します（環境によって 1.2.3 も受理されますが、組織内で統一してください）。破壊的変更はメジャー、後方互換の拡張はマイナー、バグ修正はパッチで表現します。

• リポジトリ: terraform-<provider>-<name>（例: terraform-azurerm-network）
• タグ規約: vMAJOR.MINOR.PATCH（例: v1.4.2、プリリリースは v1.5.0-rc1）
• CHANGELOGとREADMEは必ず更新。examples/ ディレクトリで使用例も同梱
• outputs/variablesは安易に破壊的変更を入れない。deprecatedを明示し段階的に除去

タグとCHANGELOGの例（規約サンプル）

リポジトリ名: terraform-aws-vpc

タグ: v1.2.0
CHANGELOG.md 抜粋:
- feat: Add flow logs support (#123)
- fix: Correct IGW dependency (#125)
- docs: Update examples for multi-AZ (#126)

次の破壊的変更を予定:
- v2.0.0 で variable "enable_classiclink" を削除（EOLに伴う）

発行と消費のワークフロー（Terraform Cloud/Enterprise）

発行側は、VCSにタグを打つだけです。Terraform Cloud/EnterpriseのPMRがタグを検出し、新しいバージョンとして登録します。消費側はレジストリ形式のsourceを指定し、version制約を与えます。

CLIは app.terraform.io への認証が必要です。terraform login でクレデンシャルを作成（~/.terraform.d/credentials.tfrc.json）し、init時に自動で取得します。

• VCS連携はorg設定で一度だけ。以後は repo 作成とタグで自動登録
• 開発ブランチに対してはCIで validate/plan を実施、タグ打ちはレビュー後に限定
• 消費側は version = "~> 1.2" のように安全側に制約を置く（マイナー互換範囲）
• Git参照へ戻したい場合は source を git:: に、固定は ref= を使う

Git参照とレジストリ参照の対比（正/誤）

# 正: レジストリ参照は version が使える
module "vpc" {
  source  = "app.terraform.io/acme/vpc/aws"
  version = ">= 1.2, < 2.0"
}

# 正: Git参照は ref= で固定（version は書かない）
module "vpc_git" {
  source = "git::https://git.example.com/terraform-aws-vpc.git?ref=v1.2.3"
}

# 誤: Git参照に version を併記（エラーになる）
module "vpc_bad" {
  source  = "git::https://git.example.com/terraform-aws-vpc.git?ref=v1.2.3"
  version = "~> 1.2"  # ← サポートされない
}

権限・可視性・監査の設計

PMRの利用可否は組織メンバーシップとチーム権限設計に依存します。発行（Publish）やモジュール管理（Admin）は限定し、消費（Read/Use）は広めに付与するのが基本です。実運用では「発行はモジュールメンテナーチームのみ」「消費は全開発者」といった分担が多いです。

監査については、誰がどのバージョンをいつ参照したかはTerraform Cloud/Enterpriseの実行ログ、VCSのタグ履歴、レビュー履歴を突き合わせるのが定石です。取り下げは原則禁止として、新しいパッチ版での修正提供を徹底します。

• 発行権限は最小化（レビュー必須 + タグ保護）
• 消費はorg内に広く公開。ネットワーク境界内で完結
• 破壊的変更はメジャーバンプ + 移行ガイド提供
• バージョン削除は避ける。代替として非推奨の明記と新パッチ提供

レポ構成・CIテスト・互換性の維持

モジュールは examples/ で最小構成と代表ユースケースを実行可能にし、CIで terraform fmt -check, validate, tflint, 可能ならTerratest/Kitchen-Terraformを走らせます。PR時にexamplesがplan/applyできることを確認できるのが理想です。

互換性は versions.tf で required_version と required_providers を明示し、出力・入力スキーマの変更は段階的に。0→1の破壊的変更は避け、メジャーでのみ行います。

• ディレクトリ: modules/ は不要（単一リポ想定）。rootに main/variables/outputs
• examples/complete, examples/minimal を用意しCIで実行
• providersのバージョンは厳しめに固定（~>）し、リリースノートで更新告知
• .terraform.lock.hcl はプロバイダ用。モジュールには適用されない点に注意

versions.tf（互換性を明示）

terraform {
  required_version = ">= 1.4, < 2.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.31"
    }
  }
}

# モジュールREADMEには以下を明示:
# - 対応Terraform/Providerバージョン
# - 入出力の互換性ポリシー
# - 破壊的変更の予告と移行手順

移行・トラブルシュートと試験観点

Git参照からPMR参照への移行は、まず既存タグをSemVerに整え、PMRで認識させてから module.source を置換します。既存ワークスペースでは terraform init -upgrade を実行して解決情報を更新します。

典型的なエラーは、命名規約不一致（terraform-<provider>-<name>でない）、タグ未作成、versionとgit::の併用、認証漏れ（credentials.tfrc.json未設定）です。

• タグはSemVerに正規化。v1.2.3 推奨（環境差異に注意）
• module version はレジストリ参照でのみ有効。Gitではref=のみ
• init時の401/403はトークン・組織権限・VCS連携を確認
• 最小再現: 新規ディレクトリで module だけ配置し terraform init を試す

移行の置換例（Git → PMR）

# 変更前（Git参照）
module "vpc" {
  source = "git::https://git.example.com/terraform-aws-vpc.git?ref=v1.2.0"
}

# 変更後（PMR参照）
module "vpc" {
  source  = "app.terraform.io/acme/vpc/aws"
  version = "~> 1.2"
}

問題で確認

よくある質問