Terraform共有モジュール戦略: 組織横断の再利用を実現する実務

チームや事業部ごとにTerraformコードが増えると、命名、タグ、セキュリティ基準、ネットワーク構成などの差異が運用負債になります。共有モジュールを戦略的に整えることで、横断的な再利用と統制を両立できます。

本稿では、公式ドキュメントに沿った安定的な概念に基づき、モジュールの設計原則、プロバイダと依存関係の扱い、配布とバージョニング、テストとリリースを実務目線で解説します。Professionalレベルの試験で問われやすい論点も明示します。

原則とゴール: 共有モジュールで解くべき問題の明確化

共有モジュールの第一目標は、反復するインフラ要素を安全かつ一貫して提供することです。設計は「消費者（利用チーム）が誤りにくいAPI」を最優先にします。Terraformの安定概念（ルート/子モジュール、入力変数、出力、required_providers、バージョン制約、Private Registry）を土台に据えると、長期運用に耐えます。

試験観点では、モジュールは状態やバックエンドを内包しないこと、プロバイダはルートで定義して子に明示的に渡せること、そしてセマンティックバージョニングを用いた互換性管理が要点です。

• APIファースト: 変数は型と検証を定義し、デフォルトは安全側に寄せる
• 最小権限と強制タグなどの組織ポリシーをモジュールで標準化
• 子モジュールは状態バックエンドや認証情報を持ち込まない（ルート責務）
• 互換性の約束（SemVer）と移行ガイド（CHANGELOG、DEPRECATION）を運用に組み込む
• 公式機能を優先（Private Registry、required_providers、version constraints）

共有モジュール最小スケルトン例

terraform {
  required_version = ">= 1.0.0"
  required_providers {
    aws = {
      source = "hashicorp/aws"
      # バージョン制約は必要に応じて設定（例: ">= 4.0"）
    }
  }
}

# main.tf
# 組織標準タグを強制する例
variable "name" {
  type        = string
  description = "リソースの論理名"
}

variable "tags" {
  type        = map(string)
  description = "追加タグ（標準タグとマージ）"
  default     = {}
}

locals {
  standard_tags = {
    owner      = "platform"
    managed-by = "terraform"
  }
  merged_tags = merge(local.standard_tags, var.tags)
}

# ここにリソースを定義し、tags = local.merged_tags を適用

output "id" {
  value       = "example-id"
  description = "作成したリソースのID"
}

インターフェース設計: 入出力、バリデーション、安定性の管理

入力は型、検証、記述を必ず定義し、利用者が値の意味と制約を即時に理解できるようにします。sensitiveフラグは機密値の誤出力を防ぎ、nullableやデフォルトの扱いは慎重に。出力は下位互換性を壊さない命名とスキーマで維持します。

マップ・オブジェクト型は将来拡張に強い一方、過剰な入れ子は学習コストを上げます。モジュールのAPIは80%ユースケースを簡単に、20%は拡張点（任意のタグ、ポリシードキュメント受け取り等）で吸収する構成が現実的です。

• 変数に型/description/validation/sensitiveを付与
• 安全側のデフォルト（例: 暗号化有効、公開アクセス無効）
• 出力の互換性: 既存キーの削除・意味変更はメジャー更新でのみ実施
• map(string)やobject({ ... })で将来拡張を確保
• ドキュメントは変数・出力の挙動と例をセットで提示

変数の型・検証・機密指定の例

variable "cidr_block" {
  type        = string
  description = "VPCのCIDR。RFC1918内で指定"
  validation {
    condition     = can(cidrnetmask(var.cidr_block))
    error_message = "有効なCIDRを指定してください。"
  }
}

variable "enable_public_subnets" {
  type        = bool
  description = "パブリックサブネットを作成するか"
  default     = false
}

variable "admin_password" {
  type        = string
  description = "管理用パスワード"
  sensitive   = true
}

output "vpc_id" {
  value       = aws_vpc.this.id
  description = "作成したVPCのID"
}

プロバイダと依存の扱い: ルートで定義し子に渡す

子モジュールは required_providers を宣言しますが、具体的なプロバイダ設定（認証、リージョン、エイリアス）はルートモジュールで行い、providers引数で渡します。これにより、認証情報や接続先の責務がルートに集約され、再利用性と安全性が増します。

バックエンド設定は常にルートモジュールの責務です。子モジュールにbackendブロックを含めないのが公式の推奨に合致します。

• 子: terraform { required_providers {...} } はOK、providerブロックは原則持たない
• ルート: providerブロック定義、必要ならaliasを付与
• moduleブロックのproviders引数でエイリアス付きインスタンスを渡す
• データソース・外部依存は明示的に入力で受け取りやすく設計
• backendはルート限定（子で定義しない）

ルートでのプロバイダ定義と子モジュールへの受け渡し

provider "aws" {
  region = "us-east-1"
  alias  = "use1"
}

module "network" {
  source    = "app/network/aws"
  version   = "~> 1.2"
  providers = {
    aws = aws.use1
  }
  name       = "core"
  cidr_block = "10.0.0.0/16"
}

配布とリポジトリ戦略: Private Registryとモノレポ/マルチレポ

Terraform Cloud/EnterpriseのPrivate RegistryやVCS連携により、SemVerタグでバージョン付けされたモジュールを組織内に公開できます。命名規則（<namespace>/<name>/<provider>）を統一し、README・使用例・互換性ポリシーを必ず添付します。

リポジトリ構成はモノレポとマルチレポに大別できます。依存分離、リリース粒度、CI効率、アクセス制御の観点で選定し、どちらでもタグ駆動のバージョン管理を徹底します。

• VCSのリリースタグ（v1.2.3）でPrivate Registryに自動公開
• 命名は <org>/<module>/<provider> を統一
• READMEに入力/出力/例/互換性方針/サポート範囲を明記
• 公開前にvalidate/fmt/静的チェック/例でのplanを必須化
• 破壊的変更はメジャー更新＋移行手順を同時公開

共有モジュール配布の全体像

タグ駆動のリリース（例）

# 変更コミット後にSemVerタグを付与
$ git tag v1.2.0
$ git push origin v1.2.0
# VCS連携されたPrivate Registryがタグを検出し、モジュールv1.2.0を公開

バージョニングと互換性: SemVerと制約の使い分け

モジュールはセマンティックバージョニングに従い、破壊的変更をメジャーにのみ含めます。マイナーは後方互換の追加、パッチは不具合修正に限定します。CHANGELOGに差分と移行手順を書き、Deprecatedは事前予告期間を設けます。

消費側はversion引数で制約を指定します。~> は右端のみを可変にするのに便利で、>= と < を組み合わせると上限も含めて厳密に管理できます。

• 破壊的変更はメジャー更新＋移行ガイド必須
• Deprecatedは2リリース程度の猶予を設定し警告を出す
• 消費側は一気にlatestへ飛ばさず段階更新
• モジュールの出力変更は互換層（旧出力を残す）で緩和

消費側でのバージョン制約例

module "network" {
  source  = "app/network/aws"
  version = "~> 1.4"      # 1.4.x に固定（将来2.0系は拾わない）
  # あるいは厳密に
  # version = ">= 1.4.0, < 2.0.0"
}

検証とリリース: 誰でも安全に出せる仕組み

モジュールは単体でterraform validate/fmtが通ること、examplesディレクトリでの最小使用例がplan可能であることをゲートにします。CIはlintよりもまず公式のvalidate/fmt/初期化と、例に対するplanの安定実行を重視します。

最近のTerraformにはテスト支援機能が追加されていますが、導入は組織の互換性ポリシーに従い段階的に進めてください。まずは不変の公式コマンドでの検証をパイプラインに固定し、破壊的変更の検出をCHANGELOGとレビューで補完します。

• module直下で terraform fmt -check, terraform init -backend=false, terraform validate
• examples/ 最小構成で terraform init/plan を実行し成功を確認
• Registry公開はCIからのみ（手動禁止）
• リリースノートと互換性ラベル（Added/Changed/Deprecated/Removed/Fixed/Security）を標準化
• 消費スタックでの段階ロールアウトとロールバック手順を用意

モジュールCIの最小検証ステップ（例）

#!/usr/bin/env bash
set -euo pipefail

# 1) コード整形と基本検証
terraform -chdir=. fmt -check -diff
terraform -chdir=. init -backend=false
terraform -chdir=. validate

# 2) 最小使用例でのplan（状態は書かない）
terraform -chdir=examples/minimal init -backend=false
terraform -chdir=examples/minimal plan -input=false -lock=false -refresh=false -var "name=ci-test"

問題で確認

よくある質問