Terraform Input Variables 実務・Associate対策: variable ブロック設計の要点

Terraform の input variable は、モジュールの「公開インターフェイス」です。丁寧に設計すると再利用性が上がり、現場の事故（型不一致や値の取り違え）も避けられます。一方で、型や優先順位の理解が曖昧だと、意図しない値が適用されたり、秘密情報が出力に混ざるなどのトラブルが起きがちです。

ここでは、公式ドキュメントの挙動に沿って、variable ブロックの型設計、検証、機密扱い、値の優先順位、モジュール境界での渡し方を整理します。Terraform Associate 試験で頻出の観点も示しながら、手元のコードにすぐ取り入れられる実装パターンを提示します。

variable ブロックの基本と前提

variable ブロックは、モジュールに与える外部入力の定義です。名前、型、説明、デフォルト、検証、機密フラグなどを宣言します。デフォルトが無い変数は「必須入力」となり、計画・適用時に値の供給が必要です。

Terraform は宣言的であり、変数は「状態を持つ」のではなく「評価時に解決」されます。したがって、どこから値が供給され、どの値が最終的に採用されるのか（優先順位）を正しく理解することが、設計上の出発点になります。

• description は必ず書く。モジュールの利用者にとっての仕様書になる
• 型は可能な限り厳格に（後述）。string に何でも入れるのは避ける
• デフォルト未指定は required。指定があると optional になる
• sensitive は出力やログでのマスキングに効くが、state の暗号化ではない

型設計: primitive, collection, structural の使い分け

型は variable 設計の中核です。プリミティブ（string/number/bool）、コレクション（list/set/map）、構造（object/tuple）を使い分けることで、入力の曖昧さを排除できます。特に list と set、map と object の違いは試験でも実務でも重要です。

可能な限り「使い方に合った最も厳格な型」を選びます。後からの破壊的変更を避けるため、将来の拡張が見込まれる入力は object でスキーマ化するのが無難です。

• list は順序あり・重複可、set は順序なし・一意
• map(string) は自由鍵の辞書、object は固定スキーマの構造
• tuple は位置と型が固定。外部入力では使い所が限られる
• any は最後の手段。検証と併用して安全性を担保する

default・nullable・sensitive・validation の設計

入力の安全性と利用体験は、属性設計で大きく変わります。default を与えると optional、未指定だと required です。validation ブロックで受理範囲を明示し、エラーを早期発見しましょう。sensitive は計画出力や UI でのマスキングに効きますが、state の秘匿化ではありません（バックエンドの暗号化を別途検討）。

Terraform 1.x では nullable を指定して null の受け入れ可否を制御できます。プロバイダや言語仕様のバージョンにより細部の挙動が異なる場合があるため、チームのバージョンを固定してから導入すると安全です。

• validation の error_message は具体的に
• sensitive な値は output にそのまま渡さない
• default=null を使う場合は、locals でフォールバックを一元化
• 数値や範囲は明示的にチェック（>=、<= など）

変数ブロック例: 型制約・検証・機密・null 戦略

variable "environment" {
  type        = string
  description = "デプロイ環境: dev/stg/prod"
  validation {
    condition     = contains(["dev", "stg", "prod"], var.environment)
    error_message = "environment は dev, stg, prod のいずれかにしてください。"
  }
}

variable "instance_count" {
  type        = number
  description = "作成するインスタンス数"
  default     = 2
  validation {
    condition     = var.instance_count >= 1 && var.instance_count <= 20
    error_message = "instance_count は 1〜20 の範囲で指定してください。"
  }
}

variable "tags" {
  type        = map(string)
  description = "共通タグ"
  default     = {}
}

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

variable "optional_domain" {
  type        = string
  description = "省略可のカスタムドメイン。未設定なら null"
  default     = null
  nullable    = true
}

variable "network" {
  type = object({
    vpc_id        = string
    subnet_ids    = list(string)
    enable_public = bool
  })
  description = "ネットワーク設定"
}

locals {
  # null や空をフォールバック
  effective_tags = length(var.tags) > 0 ? var.tags : {
    "managed-by" = "terraform"
  }
}

resource "example_instance" "this" {
  count = var.instance_count
  name  = "${var.environment}-app-${count.index}"
  tags  = local.effective_tags
  # 注意: var.admin_password を平文で出力に流さない。
}

モジュール境界での変数設計

モジュールを再利用可能にする鍵は、入力インターフェイスの安定性です。関連する値は object にまとめ、利用者にとって意味のある単位で渡せるようにします。タグのような任意キー集合は map(string)、スキーマが固定の設定群は object が適します。

破壊的変更（型の変更、必須化など）はモジュールのバージョニングで管理します。required/optional の切り替えは利用者影響が大きいので、optional 化は default または null 受け入れ＋locals フォールバックで進めるのが無難です。

• module 入力は var. で参照（var.name など）
• 構造は object、選択肢は string＋validation、ブーリアン分岐は bool で明確化
• 可変要素は map/list、集合的操作（重複排除）は set を選ぶ
• 将来拡張が見込まれる場合は object に余白（後方互換の追加）を確保

値の渡し方と優先順位（tfvars・環境変数・CLI）

同じ変数に複数の供給源がある場合、Terraform は決められた優先順位で最終値を選びます。より「明示的な」指定が強く、最後に解決されたものが採用されます。Associate でも頻出です。

自動読込されるファイル（terraform.tfvars、*.auto.tfvars）と、CLI で明示する -var/-var-file の違いを押さえておきましょう。環境変数 TF_VAR_name は低い優先度で、デフォルト値の上書きに使えます。

• 同一キーが複数に存在すると、優先順位の高い供給源が採用
• ファイル拡張子 .tfvars.json もサポート（JSON 形式）
• -var は個別指定、-var-file はまとまった指定に向く
• Terraform Cloud/Enterprise のワークスペース変数は別系統（本稿ではローカル中心）

変数値の優先順位（左=低 → 右=高）

アンチパターンとチェックリスト

変数設計で陥りがちな落とし穴をまとめます。レビュー時のチェックリストとしても使えます。

特に any の乱用、string で真偽値を扱う、validation 未設定、sensitive の放置は典型的な事故要因です。

• string で true/false を渡さない（bool を使う）
• type = any は避け、やむを得ず使うなら厳格な validation を併用
• validation を省かない（範囲・選択肢・フォーマット）
• sensitive を output に直接流さない。state 暗号化/保護も別途検討
• list と set の違いを無視しない（順序 vs 一意性）
• 関連値は object にまとめる（引数リストの肥大化を防ぐ）

問題で確認

よくある質問