目次

• はじめに
  • 全体像
• TFLint
  • TFLintとは
  • 導入手順
• Checkov
  • Checkovとは
  • 導入手順
• terraform-docs
  • terraform-docsとは
  • 導入手順
• まとめ

はじめに

TerraformはInfrastructure as Code（IaC）の代表的なツールとして広く利用されており、インフラ構成をコードとして管理することで、構築作業の自動化や構成管理の効率化を実現できます。

一方で、Terraformの利用が進むにつれてコード量や管理対象のリソースは増加し、命名規則の統一、セキュリティ設定の確認、ドキュメントの維持といった運用面の課題も発生します。

これらを人手によるレビューのみで管理していると、確認漏れや属人化、レビュー工数の増加につながるため、継続的に品質を担保できる仕組みづくりが重要になります。

この記事では、Terraform運用における品質管理やドキュメント管理の自動化を支援するツールとして、TFLint・Checkov・terraform-docsを紹介します。

なお、TerraformによるAWSインフラ構築やCI/CDパイプライン構築については、以下の記事も参考にしてください。

• Terraformを使ってクラウドインフラ構築
• Terraformを使ったクラウドインフラ構築 応用・活用編
• 実践 CI/CD クラウドインフラ構築・運用省力化

全体像

以下は、Terraformの品質チェックとドキュメント管理を自動化する際のCI/CDパイプライン例です。

各ツールの役割は以下の通りです。

• terraform fmt：コードフォーマットの統一
• terraform validate：Terraform構文や設定の妥当性を確認
• TFLint：命名規則やベストプラクティスを検証
• Checkov：セキュリティやコンプライアンスを検証
• terraform-docs：README（リソース管理ドキュメント）を自動生成

TFLint

TFLintとは

TFLintはTerraform専用の静的解析ツールです。

Terraformコードを解析し、命名規則違反や非推奨な記述、ベストプラクティスに反する設定を検出できます。Terraform標準のterraform validateが構文や設定の妥当性を確認するのに対し、TFLintは命名規則やモジュール構成、クラウドプロバイダーの推奨設定など、より実践的な品質チェックを実施できます。

また、AWS・Azure・Google Cloud向けのルールセットをプラグインとして追加できるため、利用しているクラウド環境に応じてチェックを実施できます。

TFLintはOSSとしてGitHub（ https://github.com/terraform-linters/tflint ⧉ ） で公開されており、現在もTerraformの新バージョンへの対応やルールセットの改善が継続的に実施されています。

特徴

• Terraformのベストプラクティスに基づいたコードチェックを実施できる
• terraform validateでは検出できない非推奨な記述を検出できる
• AWS向けルールセットを利用することで、AWSリソースの推奨設定を確認できる
• 命名規則やモジュール構成の統一に役立つ

注意点

• セキュリティやコンプライアンスの観点はカバーできない
• プロジェクト独自ルールは別途設定が必要になる

導入手順

1. インストール

Releases · terraform-linters/tflint ⧉ よりインストールします。

2. 設定ファイルの配置

.tflint.hcl を任意の場所に配置し、環境変数 TFLINT_CONFIG_FILE にファイルパスを登録します。

以下はTerraform Rulesetで提供されているルールを利用した設定例です。利用可能なルール一覧は以下を参照してください。

https://github.com/terraform-linters/tflint-ruleset-terraform/blob/main/docs/rules/README.md ⧉

.tflint.hcl

1
config {
2
  call_module_type = "all"
3
}
4

5
plugin "aws" {
6
  enabled = true
7
  version = "0.47.0"
8
  source  = "github.com/terraform-linters/tflint-ruleset-aws"
9
}
10

11
# Terraformリソース名や変数名などが命名規則に従っていることを確認するルール
12
rule "terraform_naming_convention" {
13
  enabled = true
14
}
15

16
# コメントが#で記載されていることを確認するルール（//は使わない）
17
rule "terraform_comment_syntax" {
18
  enabled = true
19
}
20

21
# variableブロックやoutputブロックがvariables.tfやoutputs.tfで定義されていることを確認するルール
22
rule "terraform_standard_module_structure" {
23
  enabled = true
24
}

3. プラグインの初期化

任意のディレクトリで以下を実行します。

1
tflint --init

初回実行時にAWSルールセットなどのプラグインがダウンロードされ、ローカル環境に配置されます。

4. 実行

Terraformコード（.tfファイル）が配置されているディレクトリで実行します。

1
tflint

ルートモジュール（providers.tf が配置されているディレクトリ）で実行する場合は、事前にTerraformの初期化が必要です。

1
terraform init
2
tflint

5. 実行結果例

以下は、variableブロックがvariables.tf以外で定義されている場合の実行結果例です。

1
1 issue(s) found:
2

3
Warning: variable "environment" should be defined in variables.tf
4

5
  on main.tf line 10:
6
  10: variable "environment" {
7

8
Reference: https://github.com/terraform-linters/tflint-ruleset-terraform

Checkov

Checkovとは

CheckovはBridgecrewが開発したTerraformやCloudFormationなどのIaCを対象としたセキュリティ静的解析ツールです。

コードを実際にクラウドへデプロイする前に、セキュリティリスクやコンプライアンス違反、設定不備を検出できます。TFLintがコード品質やベストプラクティスの確認を目的としているのに対し、Checkovは暗号化設定やネットワーク公開設定など、セキュリティ観点のチェックを実施できます。

また、TerraformだけでなくCloudFormation・Kubernetes・Helm・AWS CDKなど幅広いIaCに対応しており、独自ポリシーを追加することで組織固有のセキュリティルールも適用できます。

CheckovはOSSとして、GitHub（ https://github.com/bridgecrewio/checkov ⧉ ） で公開されており、現在も継続的にルール追加や機能改善が行われています。

特徴

• Terraformに対するセキュリティチェックを実施できる
• セキュリティだけでなくコンプライアンス観点も検証できる
• カスタムポリシーによって独自ルールを追加できる
• ルール単位で例外設定を行える

注意点

• 導入直後は違反が多数検出される場合がある
• プロジェクトに合わせた除外設定やルールの調整が必要になることがある

導入手順

1. インストール

Releases · bridgecrewio/checkov ⧉ よりインストールします。

2. カスタムポリシーの配置（任意）

独自ルールを適用する場合、任意のディレクトリを作成し、カスタムポリシーファイルを配置します。

※ カスタムポリシーを利用しない場合、この手順は不要です。 Checkovは標準で多数のセキュリティポリシーを提供しているため、標準ポリシーのみでも利用可能です。

1
tools/checkov_policies/required_tags.yaml

以下はカスタムポリシーのサンプルです。プロジェクトの要件に合わせて追加・調整してください。

required_tags.yaml（全リソースにNameタグが付与されていることを確認）

1
---
2
metadata:
3
  name: "Check that all resources are tagged with the key - Name"
4
  id: "CUSTOM_REQUIRED_TAGS"
5
  category: "GENERAL_SECURITY"
6
scope:
7
  provider: aws
8
definition:
9
  cond_type: "attribute"
10
  resource_types: "taggable"
11
  attribute: "tags.Name"
12
  operator: "exists"

3. tfplan.jsonの作成

変数展開後の実際の値に対してチェックするため、terraform plan の結果をJSON形式に変換します。

1
terraform init
2
terraform plan --out tfplan.binary
3
terraform show -json tfplan.binary > tfplan.json

これにより、実際に作成されるリソース構成に対してセキュリティチェックを実施できます。

4. 実行

tfplan.json が配置されているディレクトリで以下を実行します。

1
checkov -f tfplan.json

カスタムポリシーを利用する場合は、 --external-checks-dir でカスタムポリシーの配置先を指定します。

1
checkov -f tfplan.json \
2
  --external-checks-dir tools/checkov_policies

5. 実行結果例

以下は、S3バケットのパブリックアクセス設定に問題がある場合の実行結果例です。

1
Check: CKV_AWS_53
2
FAILED for resource: aws_s3_bucket.example
3

4
Resource: aws_s3_bucket.example
5
File: /tfplan.json
6

7
Ensure S3 bucket has block public ACLS enabled
8

9
Guide: https://docs.bridgecrew.io/docs/s3_1

terraform-docs

terraform-docsとは

terraform-docsはTerraformコードからREADMEを自動生成するツールです。

.tfファイルに記載されたリソース・変数・出力値などの情報を読み取り、Markdown形式のREADMEとして出力します。各モジュール・環境ディレクトリのREADMEをリソース管理ドキュメントとして活用できます。

terraform-docsはOSSとしてGitHub（ https://github.com/terraform-docs/terraform-docs ⧉ ） で公開されており、現在も継続的に機能追加や改善が行われています。

特徴

• Terraformコードをもとにドキュメントを作成できる
• コードとドキュメントの整合性を維持しやすい
• モジュールや環境ごとのドキュメント形式を統一できる
• Terraformの構成やパラメータを把握しやすくなる

注意点

• ドキュメント品質を維持するために、リソースや変数へコメントを記載する運用が必要になる
• Terraformコードに記載されていない情報は出力できない

導入手順

1. インストール

Releases · terraform-docs ⧉ よりインストールします。

2. テンプレートファイルの配置

terraform-docsは .terraform-docs.yml に出力内容を定義することで、複数のモジュール・環境ディレクトリで統一されたドキュメント形式を維持できます。

以下は設定例です。要件に応じて出力内容を調整してください。

.terraform-docs.yml

1
formatter: markdown
2

3
output:
4
  file: README.md
5
  mode: inject
6

7
sections:
8
  show:
9
    - requirements
10
    - providers
11
    - modules
12
    - resources
13
    - inputs
14
    - outputs
15

16
content: |-
17
  {{ .Requirements }}
18

19
  {{ .Providers }}
20

21
  ## Modules
22
  | Name | Source | Description |
23
  | ---- | ------ | ----------- |
24
  {{- range .Module.ModuleCalls }}
25
  {{- $name := printf "%s" .Name }}
26
  {{- $prefix := printf "%.5s" $name }}
27
  {{- if ne $prefix "data_" }}
28
  | {{ $name }} | {{ printf "%s" .Source }} | {{ .Description }} |
29
  {{- end }}
30
  {{- end }}
31

32
  ## Data Modules
33
  | Name | Source | Description |
34
  | ---- | ------ | ----------- |
35
  {{- range .Module.ModuleCalls }}
36
  {{- $name := printf "%s" .Name }}
37
  {{- $prefix := printf "%.5s" $name }}
38
  {{- if eq $prefix "data_" }}
39
  | {{ $name }} | {{ printf "%s" .Source }} | {{ .Description }} |
40
  {{- end }}
41
  {{- end }}
42

43

44
  ## Resources
45
  | Type | Name | Description |
46
  | ---- | ---- | ----------- |
47
  {{- range .Module.Resources }}
48
  | {{ .Type }} | {{ .Name }} | {{ .Description }} |
49
  {{- end }}
50

51
  {{ .Inputs }}
52

53
  {{ .Outputs }}
54

55
sort:
56
  enabled: true
57
  by: required

テンプレートのカスタマイズ例

READMEをより実用的なリソース管理ドキュメントとして活用するために、テンプレートをカスタマイズすることもできます。

リソース一覧を説明付きで出力

標準の出力内容に加え、リソースタイプやリソース名だけでなくDescriptionも出力しています。

1
## Resources
2
| Type | Name | Description |
3
| ---- | ---- | ----------- |
4
{{- range .Module.Resources }}
5
| {{ .Type }} | {{ .Name }} | {{ .Description }} |
6
{{- end }}

これにより、READMEを確認するだけでリソースの用途が把握できます。

コメントルールの活用

DescriptionをREADMEに出力する場合、Terraformコード側のコメントルールも重要になります。

コメントには単なる説明だけでなく、リソースの役割や特徴、環境差分などを記載することで、README上でも用途や設計意図を把握しやすくなります。

TerraformのリソースブロックにはDescriptionフィールドがないため、リソースの直前にコメントとして記載します。また、<br> を使用することで、Description列内で改行できます。

生成結果のDescription列には、これらのコメントが出力されます。

1
# [役割]: ECSサービス用のセキュリティグループ
2

3
# [特徴]: ALBからの通信のみ許可
4

5
# [環境差分]: なし
6
resource "aws_security_group" "ecs" {
7
  ...
8
}

3. READMEの作成

READMEはTerraformコードを管理しているディレクトリごとに配置します。各ディレクトリにREADMEを配置することで、ディレクトリ単位のリソース管理ドキュメントとして活用できます。

1
ecs/
2
├── README.md
3
├── main.tf
4
├── variables.tf
5
└── outputs.tf

READMEには以下のコメントを記載します。terraform-docs実行時に、この範囲にドキュメントが自動生成されます。

1
# ECS
2

3
<!-- BEGIN_TF_DOCS -->
4
<!-- END_TF_DOCS -->

4. 実行

READMEを配置したディレクトリで以下を実行します。

1
terraform-docs markdown table \
2
  --config .terraform-docs.yml \
3
  --output-file README.md .

5. 生成結果

READMEのコメント範囲には、テンプレートで指定した情報が自動生成されます。

1
## Requirements
2

3
| Name      | Version  |
4
| --------- | -------- |
5
| terraform | >= 1.6.0 |
6

7
## Providers
8

9
| Name | Version |
10
| ---- | ------- |
11
| aws  | >= 5.0  |
12

13
## Modules
14

15
| Name            | Source                    | Description        |
16
| --------------- | ------------------------- | ------------------ |
17
| app_ecs_service | ../../modules/ecs_service | ECS Service Module |
18
| app_alb         | ../../modules/alb         | ALB Module         |
19

20
## Resources
21

22
| Type               | Name | Description                                                                                      |
23
| ------------------ | ---- | ------------------------------------------------------------------------------------------------ |
24
| aws_security_group | ecs  | [役割]: ECSサービス用のセキュリティグループ
25
[特徴]: ALBからの通信のみ許可
26
[環境差分]: なし |
27
| aws_ecs_service    | ecs  | [役割]: ECSサービスを構築する
28
[特徴]: Application Load Balancerと連携
29
[環境差分]: なし     |
30

31
## Inputs
32

33
| Name        | Description | Type   | Default |
34
| ----------- | ----------- | ------ | ------- |
35
| environment | 環境識別子  | string | n/a     |
36

37
## Outputs
38

39
| Name                  | Description                         |
40
| --------------------- | ----------------------------------- |
41
| ecs_security_group_id | ECSサービス用セキュリティグループID |

まとめ

この記事では、Terraform運用を支援する以下のツールを紹介しました。

• TFLint：命名規則やベストプラクティスを検証
• Checkov：セキュリティやコンプライアンスを検証
• terraform-docs：README（リソース管理ドキュメント）を自動生成

TFLint・Checkov・terraform-docsを組み合わせることで、Terraformコードの品質チェックからセキュリティ検証、ドキュメント管理まで自動化できます。

また、CI/CDパイプラインに組み込むことで、品質チェックやドキュメント生成を継続的に実施でき、レビュー負担の軽減や運用品質の向上が期待できます。

Terraformを利用している方は、ご自身の課題に合わせて導入を検討してみてください。