terraform-best-practices

Terraform のベストプラクティス

Terramate が管理する、Terraform と Infrastructure as Code の包括的な最適化ガイドです。10 のカテゴリにわたる 37 のルールが含まれており、自動リファクタリングとコード生成を支援するため、影響度の高い順に優先順位が付けられています。

適用するタイミング

次の場合に、これらのガイドラインを参照してください。

• 新しい Terraform モジュールや設定を作成するとき
• インフラストラクチャのパターン（AWS、GCP、Azure など）を実装するとき
• セキュリティや信頼性に関する問題についてコードをレビューするとき
• 既存の Terraform/OpenTofu コードをリファクタリングするとき
• State 管理とパフォーマンスを最適化するとき
• チームのワークフローとガバナンスを設定するとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	組織とワークフロー	CRITICAL	org-
2	State 管理	CRITICAL	state-
3	セキュリティのベストプラクティス	CRITICAL	security-
4	モジュール設計	HIGH	module-
5	リソースの整理	MEDIUM-HIGH	resource-
6	変数と出力のパターン	MEDIUM	variable-、output-
7	言語のベストプラクティス	MEDIUM	language-
8	プロバイダーの設定	MEDIUM	provider-
9	パフォーマンスの最適化	LOW-MEDIUM	perf-
10	テストと検証	LOW	test-

クイックリファレンス

1. 組織とワークフロー（CRITICAL） - 5 つのルール

• org-version-control - すべての Terraform コードをバージョン管理する
• org-workspaces - 設定ごとに環境別の Workspace を 1 つずつ用意する
• org-access-control - 誰がどのインフラストラクチャを変更できるかを管理する
• org-change-workflow - インフラストラクチャの変更に正式なプロセスを設ける
• org-audit-logging - すべてのインフラストラクチャ変更を追跡する

2. State 管理（CRITICAL） - 3 つのルール

• state-remote-backend - 常にリモート State バックエンドを使用する
• state-locking - 破損を防ぐため、State ロックを有効にする
• state-import - 既存のインフラストラクチャを Terraform にインポートする

3. セキュリティのベストプラクティス（CRITICAL） - 3 つのルール

• security-no-hardcoded-secrets - コードにシークレットをハードコードしない
• security-credentials - 適切な認証情報管理（OIDC、Vault、IAM ロール）を使用する
• security-iam-least-privilege - 最小権限の原則に従う

4. モジュール設計（HIGH） - 5 つのルール

• module-single-responsibility - 論理コンポーネントごとにモジュールを 1 つ用意する
• module-naming - 一貫した命名規則（terraform--）を使用する
• module-versioning - すべてのモジュール参照にバージョンを指定する
• module-composition - 積み木のようにモジュールを組み合わせる
• module-registry - 既存のコミュニティ／共有モジュールを使用する

5. リソースの整理（MEDIUM-HIGH） - 5 つのルール

• resource-naming - 一貫した命名規則を使用する
• resource-tagging - コスト追跡のため、すべてのリソースにタグを付ける
• resource-lifecycle - ライフサイクルブロック（prevent_destroy、ignore_changes）を使用する
• resource-count-vs-foreach - count より for_each を優先する
• resource-immutable - イミュータブルなインフラストラクチャのパターンを優先する

6. 変数と出力のパターン（MEDIUM） - 6 つのルール

• variable-types - 具体的な型、肯定形の命名、nullable を使用する
• variable-validation - 早期にエラーを検出するため、検証ルールを追加する
• variable-sensitive - シークレットを sensitive としてマークし、デフォルト値を設定しない
• variable-descriptions - すべての変数に説明を記述する
• output-descriptions - すべての出力に説明を記述する
• output-no-secrets - シークレットを直接出力しない

7. 言語のベストプラクティス（MEDIUM） - 5 つのルール

• language-no-heredoc-json - HEREDOC ではなく jsonencode/yamlencode を使用する
• language-locals - 複雑な式に名前を付けるため locals を使用する
• language-linting - terraform fmt と tflint を実行する
• language-data-sources - 値をハードコードせず、データソースを使用する
• language-dynamic-blocks - DRY なコードにするため、dynamic ブロックを使用する

8. プロバイダーの設定（MEDIUM） - 1 つのルール

• provider-version-constraints - プロバイダーのバージョンを固定する

9. パフォーマンスの最適化（LOW-MEDIUM） - 2 つのルール

• perf-parallelism - 大規模なデプロイでは並列処理を調整する
• perf-debug - トラブルシューティングのため、デバッグログを有効にする

10. テストと検証（LOW） - 2 つのルール

• test-strategies - テストピラミッド（検証、リント、計画、統合）
• test-policy-as-code - ポリシーチェックの実装（OPA、Checkov、tfsec）

使い方

詳しい説明とコード例については、個々のルールファイルをお読みください。

rules/state-remote-backend.md
rules/security-no-hardcoded-secrets.md
rules/module-versioning.md

各ルールファイルには、次の内容が含まれています。

• 重要な理由の簡単な説明
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• 追加の背景情報と参考資料

完全版のドキュメント

すべてのルールを展開した完全なガイドは、AGENTS.md をご覧ください。