tflint・terraform fmt・validateでコード品質を自動チェックする方法｜pre-commitとCIへの組み込み手順

この記事のポイント

・tflint / terraform fmt / validateは「規約違反・構文・書式」をそれぞれ担当する
・実行順序はfmt → validate → tflintの順が鉄則
・pre-commitフックに登録するとコミット前にチェックが自動実行される
・GitHub Actionsに組み込むとPRレビュー時にチェック結果が可視化される

# フォーマット修正（差分を表示しながら上書き）
$ terraform fmt

# 変更があるファイル名だけ表示（修正はしない）
$ terraform fmt --check
main.tf
variables.tf

# 終了コードで確認（0=変更なし、1=変更あり）
$ echo $?
1

# サブディレクトリも含めて再帰的に実行
$ terraform fmt -recursive

$ terraform validate
╷
│ Error: Reference to undeclared resource
│
│   on main.tf line 15, in resource "aws_instance" "web":
│   15:   subnet_id = aws_vpc.main.id
│
│ A managed resource "aws_vpc" "main" has not been declared in this module.
╵

$ echo $?
1

$ tflint
3 issue(s) found:

Warning: Missing version constraint for provider "aws" in "required_providers" (terraform_required_providers)

  on main.tf line 1:
   1: terraform {

Reference: https://github.com/terraform-linters/tflint-ruleset-terraform/blob/v0.9.1/docs/rules/terraform_required_providers.md

Warning: "t2.micro" is previous generation instance type. (aws_instance_previous_type)

  on main.tf line 10:
  10:   instance_type = "t2.micro"

Reference: https://github.com/terraform-linters/tflint-ruleset-aws/blob/v0.34.0/docs/rules/aws_instance_previous_type.md

Warning: terraform "required_version" attribute is required (terraform_required_version)

  on main.tf line 1:
   1: terraform {

# Rocky Linux 9.4 / Ubuntu 24.04 LTS どちらも同じ手順
$ TFLINT_VERSION="0.54.0"
$ curl -sLo tflint.zip \
  "https://github.com/terraform-linters/tflint/releases/download/v${TFLINT_VERSION}/tflint_linux_amd64.zip"

$ unzip tflint.zip -d /tmp/tflint
$ sudo mv /tmp/tflint/tflint /usr/local/bin/
$ sudo chmod +x /usr/local/bin/tflint

# バージョン確認
$ tflint --version
TFLint version 0.54.0
+ ruleset.terraform (0.9.1-bundled)

# 公式インストールスクリプト（curl経由）
$ curl -s https://raw.githubusercontent.com/terraform-linters/tflint/master/install_linux.sh | bash

# .tflint.hcl（リポジトリルートに配置）
config {
  # プラグインの保存先（デフォルト: ~/.tflint.d/plugins）
  plugin_dir = ".tflint.d/plugins"
}

# Terraform基本ルールセット（バンドル済み）
plugin "terraform" {
  enabled = true
  version = "0.9.1"
  source  = "github.com/terraform-linters/tflint-ruleset-terraform"

  # 推奨ルールを一括有効化
  preset = "recommended"
}

# AWSプロバイダー固有のルールセット
plugin "aws" {
  enabled = true
  version = "0.34.0"
  source  = "github.com/terraform-linters/tflint-ruleset-aws"
}

# 特定ルールを無効化する例（.tflint.hclに追記）
rule "terraform_required_version" {
  enabled = false
}

$ tflint --init
Installing "terraform" plugin...
Installed "terraform" (source: github.com/terraform-linters/tflint-ruleset-terraform, version: 0.9.1)
Installing "aws" plugin...
Installed "aws" (source: github.com/terraform-linters/tflint-ruleset-aws, version: 0.34.0)

# インストール確認
$ ls .tflint.d/plugins/
github.com

# pipでインストール（Python 3.8以上が必要）
$ pip install pre-commit

# バージョン確認
$ pre-commit --version
pre-commit 3.7.1

# または pipx を使う（グローバルインストール時に推奨）
$ pipx install pre-commit

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/antonbabenko/pre-commit-terraform
    rev: v1.96.1
    hooks:
      # terraform fmt --check（フォーマットチェック）
      - id: terraform_fmt

      # terraform validate（構文・スキーマチェック）
      - id: terraform_validate

      # tflint（ベストプラクティスチェック）
      - id: terraform_tflint
        args:
          - --args=--config=__GIT_WORKING_DIR__/.tflint.hcl

# .git/hooks/pre-commitとして登録
$ pre-commit install
pre-commit installed at .git/hooks/pre-commit

# 全ファイルに対して手動で試し実行
$ pre-commit run --all-files

$ git add main.tf
$ git commit -m "add ec2 instance"
terraform_fmt...........................................................Failed
- hook id: terraform_fmt
- exit code: 1

Files were modified by this hook. Additional output:
main.tf

# terraform_fmt がファイルを自動修正したためコミットはブロックされた
# 修正後のファイルを再ステージしてコミットする
$ git add main.tf
$ git commit -m "add ec2 instance"
terraform_fmt...........................................................Passed
terraform_validate......................................................Passed
terraform_tflint........................................................Passed
[main 3f2a1b4] add ec2 instance

# .github/workflows/terraform-lint.yml
name: Terraform Lint

on:
  pull_request:
    branches:
      - main
    paths:
      - '**.tf'
      - '**.tfvars'
      - '.tflint.hcl'

jobs:
  terraform-lint:
    name: Terraform Code Quality Check
    runs-on: ubuntu-latest
    permissions:
      contents: read

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: "1.9.8"

      - name: Terraform Init
        run: terraform init -backend=false

      - name: Terraform Format Check
        run: terraform fmt --check -recursive

      - name: Terraform Validate
        run: terraform validate

      - name: Setup TFLint
        uses: terraform-linters/setup-tflint@v4
        with:
          tflint_version: v0.54.0

      - name: TFLint Init
        run: tflint --init

      - name: TFLint Run
        run: tflint --format=compact

$ tflint --init
Failed to initialize plugins; Diagnostics: ...
plugin "aws" is not installed

$ terraform validate
╷
│ Error: Could not load plugin
│
│ Plugin reinitialization required. Please run "terraform init".
│
│ Plugins are external binaries that Terraform uses to access and
│ manipulate resources. The configuration's requirements have changed
│ since the last "terraform init" ran.
╵