terraform validateの要点と構文検証のユースケース（Associate向け）

terraform validateは、構成ファイルの構文と内部整合性をオフラインで検証するコマンドです。リモートAPIには接続しないため、安全に自動化パイプラインへ組み込めます。

本稿では、試験対策（Associate）で問われやすい観点と、現場でのユースケースを同時に押さえます。特に「何が検出でき、何が検出できないのか」「initとの関係」「CIでのゲート設計」を具体的に解説します。

terraform validateの基本と適用範囲

terraform validateは、カレントディレクトリ（または指定のモジュールディレクトリ）のTerraform構成が構文的に正しく、内部的に一貫性があるかを検証します。これは静的検証であり、クラウドAPIやバックエンドにはアクセスしません。

主に検出できるのは、HCL構文エラー、型/必須属性の不整合、モジュール呼び出しの入出力不整合（インストール済みの場合）、無効なブロック/引数などです。一方で、リソースの実在確認、クラウド側制約（命名重複、権限不足、クォータ超過）などは検出できません。

モジュールやプロバイダを参照している場合、正確な検証には事前のterraform initで必要な依存関係を取得しておくことを推奨します。-jsonオプションで機械可読な出力が得られるため、CIの失敗理由集約にも向いています。

• リモートアクセスなし（安全に自動化可能）
• 構文・型・内部参照の静的検証に強い
• terraform init後の実行が実務では安定（モジュール/プロバイダ参照時）
• -jsonで機械可読な結果を出力可能

CIパイプラインにおけるvalidateの位置づけ

手元での基本検証フロー

terraform init
terraform validate
# CIで機械可読が必要な場合
terraform validate -json | jq '.diagnostics[] | {severity,summary,detail}'

CI/CDでのゲート設計と運用ポイント

validateは“落ち方が速い”ため、init直後に実行するのが定石です。構文や型の不整合はここで止め、レビュー負荷を下げます。fmt -checkと組み合わせると、スタイルと構文を同時に機械的に担保できます。

CIではノイズを抑えるため、-no-colorを付けてログを読みやすくし、-jsonを活用して失敗理由を要約します。失敗時は以降の重いジョブ（plan/apply）をスキップしてコストを抑制します。

• 順序の基本: init → validate → fmt -check → plan
• ログ最適化: -no-color, -jsonで集約
• PR専用: validate/formatのみの軽量ワークフローも有効

GitHub Actionsの最小例

name: tf-validate
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: 1.6.6
      - name: Init
        run: terraform init -input=false -no-color
      - name: Validate
        run: terraform validate -no-color

変数・型・プロバイダ制約の検証

validateは変数の型宣言とデフォルト値の整合を検証します。なお、validate自体は-varや-var-fileを受け付けないため、実際の入力値検証はplanで行います。型が厳密な場合は、デフォルト値の型不一致を早期に検出できます。

required_providersやrequired_versionの宣言は構文・制約の整合が検査されます。依存モジュールやプロバイダを利用している場合、init後でないと正しくモジュール入出力の照合ができないことがある点には注意してください。

• 型不一致（例: stringに数値デフォルト）はvalidateで即検出
• 未設定の必須変数そのものはエラーにしない（planで確認）
• プロバイダ/モジュールの取得はinitで実施してから検証

型不一致を検出する最小例

# versions.tf
terraform {
  required_version = ">= 1.5.0"
  required_providers {
    random = {
      source  = "hashicorp/random"
      version = ">= 3.5.0"
    }
  }
}

# variables.tf
variable "env" {
  type = string
  # 故意の型不一致（数値）: validateでエラー
  default = 123
}

# main.tf
output "env_out" {
  value = var.env
}

# 実行
# terraform init
# terraform validate  # => 変数型の不一致として失敗

モジュール開発時のvalidate活用

モジュール単体でも、そのディレクトリでterraform validateを実行できます。inputs/outputsの整合、不要な変数、未参照出力などを静的に洗い出します。モジュール公開前の最低限チェックとして有効です。

呼び出し側（ルートモジュール）と合わせた検証では、initでモジュール依存を取得してからvalidateを行うことで、入力変数の型/必須性の齟齬をより正確に検出できます。

• モジュール配布前にvalidateを必ず通す
• 変数にdescription/type/defaultを明記し診断の可読性を上げる
• 入出力の破壊的変更はサンプルルートでvalidate/planを併用

モジュールと呼び出し側の検証例

# modules/network/variables.tf
variable "name" {
  type        = string
  description = "network name"
}

# modules/network/outputs.tf
output "name_out" { value = var.name }

# root/main.tf
module "net" {
  source = "./modules/network"
  name   = 100  # 故意の型不一致: validateで検出
}

# 実行
# terraform init
# terraform validate  # => module.net.name に string が必要という診断

よくあるエラーと対処の実務メモ

診断メッセージはseverity（error/warning）とsummary/detailで出ます。syntax errorはファイル/行を特定しやすく、型不一致は期待型と実際の型が表示されます。モジュール解決に失敗する場合はinitの未実行や、ソースURLの誤りを疑ってください。

CIでは、validate失敗時に以降のジョブをスキップし、ログに診断のsummaryだけを残すと運用が楽になります。-json出力をjqで整形し、軽いログをPRコメントへ貼る運用が安定です。

• syntax error: カンマ/波括弧/クォートの漏れを確認
• Invalid function argument: 型/null許容を再確認
• Module not installed: terraform initの実行、sourceの見直し

validateの終了コードでゲートするBash例

set -euo pipefail
terraform init -input=false -no-color
if ! terraform validate -no-color; then
  echo "validate failed; skipping plan" >&2
  exit 1
fi
# ここまで来たらplan等を続行

問題で確認

よくある質問