--- description: 'Terraform規約とガイドライン' applyTo: '**/*.tf' --- # Terraform規約 ## 全般指針 - インフラストラクチャのプロビジョニングと管理にはTerraformを使用する。 - Terraform構成にはバージョン管理を使用する。 ## セキュリティ - 常にTerraformとそのプロバイダーの最新安定版を使用する。 - セキュリティパッチと改善を組み込むためTerraform構成を定期的に更新する。 - AWS Secrets ManagerやSSM Parameter Storeなどを使用して機密情報を安全に保存する。 - 認証情報とシークレットを定期的にローテーションする。 - 可能な場合はシークレットのローテーションを自動化する。 - AWS Secrets ManagerやSSM Parameter Storeに保存された値を参照するためAWS環境変数を使用する。 - これによりTerraformステートファイルから機密値を除外する。 - AWS認証情報、APIキー、パスワード、証明書、Terraformステートなどの機密情報をバージョン管理にコミットしない。 - `.gitignore`を使用して機密情報を含むファイルをバージョン管理から除外する。 - Terraform構成で機密変数を常に`sensitive = true`とマークする。 - これによりTerraformプランや適用出力で機密値が表示されることを防ぐ。 - リソースへのアクセスを制御するためIAMロールとポリシーを使用する。 - 権限を割り当てる際は最小権限の原則に従う。 - リソースへのネットワークアクセスを制御するためセキュリティグループとネットワークACLを使用する。 - 可能な限りプライベートサブネットにリソースをデプロイする。 - ロードバランサーやNATゲートウェイなど、直接インターネットアクセスが必要なリソースにのみパブリックサブネットを使用する。 - 保存時と転送時の機密データには暗号化を使用する。 - EBSボリューム、S3バケット、RDSインスタンスの暗号化を有効にする。 - サービス間の通信にはTLSを使用する。 - セキュリティ脆弱性についてTerraform構成を定期的にレビューおよび監査する。 - `trivy`、`tfsec`、`checkov`などのツールを使用してTerraform構成のセキュリティ問題をスキャンする。 ## モジュール性 - インフラストラクチャの各主要コンポーネントに個別のプロジェクトを使用する；これにより： - 複雑性を軽減 - 構成の管理と維持を容易にする - `plan`と`apply`操作を高速化 - コンポーネントの独立した開発とデプロイメントを可能にする - 無関係なリソースへの偶発的変更のリスクを軽減 - 構成の重複を避けるためモジュールを使用する。 - 関連するリソースと構成をカプセル化するためモジュールを使用する。 - 複雑な構成を簡素化し可読性を向上させるためモジュールを使用する。 - モジュール間の循環依存関係を避ける。 - 不要な抽象化レイヤーを避ける；価値を追加する場合のみモジュールを使用する。 - 単一リソースにはモジュールを使用しない；関連リソースのグループにのみ使用する。 - モジュールの過度なネストを避ける；モジュール階層を浅く保つ。 - インフラストラクチャに関する重要な情報を公開するため`output`ブロックを使用する。 - 他のモジュールや構成のユーザーに有用な情報を提供するため出力を使用する。 - 出力で機密情報を公開することを避ける；機密データが含まれる場合は出力を`sensitive = true`とマークする。 ## 保守性 - 可読性、明確性、保守性を優先する。 - 複雑な構成となぜその設計決定をしたのかを説明するためコメントを使用する。 - 理解しやすい簡潔で効率的、慣用的な構成を記述する。 - ハードコードされた値の使用を避ける；代わりに構成に変数を使用する。 - 適切な場合は変数にデフォルト値を設定する。 - 手動構成を要求する代わりに既存リソースに関する情報を取得するためデータソースを使用する。 - これによりエラーのリスクを軽減し、構成が常に最新であることを確保し、構成が異なる環境に適応できるようにする。 - 同じ構成内で作成されるリソースにはデータソースを使用しない；代わりに出力を使用する。 - 不要なデータソースは避けるか削除する；`plan`と`apply`操作を遅くする。 - 一貫性を確保するため複数回使用される値には`locals`を使用する。 ## スタイルとフォーマット - リソース命名と構成について Terraformベストプラクティスに従う。 - リソース、変数、出力には説明的な名前を使用する。 - すべての構成で一貫した命名規則を使用する。 - フォーマットについては**Terraformスタイルガイド**に従う。 - 一貫したインデント（各レベル2スペース）を使用する。 - 関連リソースを同じファイルにグループ化する。 - リソースグループに一貫した命名規則を使用する（例：`providers.tf`、`variables.tf`、`network.tf`、`ecs.tf`、`mariadb.tf`）。 - 依存関係を明確にするためリソース定義の最初に`depends_on`ブロックを配置する。 - 循環依存関係を避けるため必要な場合のみ`depends_on`を使用する。 - リソースのインスタンス化ロジックを明確にするためリソース定義の最初に`for_each`と`count`ブロックを配置する。 - コレクションには`for_each`、数値反復には`count`を使用する。 - `depends_on`ブロックが存在する場合はその後に配置する。 - リソース定義の最後に`lifecycle`ブロックを配置する。 - 簡単なナビゲーションのため各ファイル内でプロバイダー、変数、データソース、リソース、出力をアルファベット順にする。 - ブロック内で関連属性をグループ化する。 - オプション属性の前に必須属性を配置し、各セクションを適切にコメントする。 - 可読性を向上させるため空行で属性セクションを分離する。 - 簡単なナビゲーションのため各セクション内で属性をアルファベット順にする。 - 構成の論理セクションを分離するため空行を使用する。 - 構成を自動的にフォーマットするため`terraform fmt`を使用する。 - 構文エラーをチェックし構成が有効であることを確保するため`terraform validate`を使用する。 - スタイル違反をチェックし構成がベストプラクティスに従っていることを確保するため`tflint`を使用する。 - 開発プロセスの早い段階でスタイル問題をキャッチするため`tflint`を定期的に実行する。 ## 文書化 - 変数と出力には常に`description`と`type`属性を含める。 - 各変数と出力の目的を説明するため明確で簡潔な説明を使用する。 - 変数に適切な型を使用する（例：`string`、`number`、`bool`、`list`、`map`）。 - 適切な場合はコメントを使用してTerraform構成を文書化する。 - リソースと変数の目的を説明するためコメントを使用する。 - 複雑な構成や決定を説明するためコメントを使用する。 - 冗長なコメントを避ける；コメントは価値と明確性を追加すべき。 - プロジェクトの概要とその構造を提供するため各プロジェクトに`README.md`ファイルを含める。 - 構成のセットアップと使用のための指示を含める。 - 構成の文書を自動的に生成するため`terraform-docs`を使用する。 ## テスト - Terraform構成の機能を検証するためテストを記述する。 - テストファイルには`.tftest.hcl`拡張子を使用する。 - 正の場合と負の場合の両方のシナリオをカバーするテストを記述する。 - テストが冪等で副作用なしに複数回実行できることを確保する。