Infrastructure Development Guidelines
AI駆動開発でインフラを構築する際に使えるインフラストラクチャ開発ガイドラインの解説です。AWSとTerraform対応。
Project Information（プロジェクト情報）
- クラウドプラットフォームとしてAWSを使用する
- 環境名はproduction、staging、development、experimentalとする
- インフラストラクチャはTerraformを使用して構築および運用する
Design（設計）
- 重要なリソースとデータは常にバックアップする
- サービスの監視とアラート機構を準備する
- AWS Well-Architected Framework に従って実装する
- 優先順位は セキュリティと信頼性、運用上の優秀性とパフォーマンス効率、コスト最適化
- 重要なリソースと操作は常にログを取る
Directory Structure（ディレクトリ構造）
Coding Standards（コーディング規約）
モジュール
命名規則
- AWSリソース名は環境名-プロジェクト名の形式で命名する
- 真偽値変数は肯定形で命名する
- モジュール内の単一リソースは main と命名する
- リソース名にリソースタイプ名を含めない
- リソース名に複数形を使用しない
- Terraformコードのリソース名はスネークケースを使用する
- モジュール内の複数リソースは役割に応じて命名する
- ストレージ単位にはMiB/GiBを使用し、その他にはMB/GBを使用する
- 数値変数名には単位を含める
スタイル
- 略語を避け、完全な名前を使用する
- 実装はAWS Well-Architected Frameworkを考慮する
- *.tfファイルのコメントを最小限に保つ
- コードから明らかな内容をコメントに書かない
- dataブロックの使用を最小限にする
- 固定値はリソース定義に直接記述してよい
- localsブロックの使用を最小限にする
- 他モジュールの呼び出しはmain.tfに定義する
- 出力ブロックで変数ブロックを参照しない
- リソースブロック属性の順序を統一する
- variableブロックの属性順序を統一する
- 埋め込み属性をできるだけ使用しない
- variableブロックはvariables.tfに定義する
- variableブロックにdefault値を設定しない
- variableとoutputブロックにdescriptionを含める
- 変数ブロックは厳密に必要な場合のみ使用する
- 環境間で同一の値には変数ブロックを使用しない
- variableブロックに型定義を含める
- 環境間でパラメータ値が異なる場合にvariableブロックを使用する
タグ
tfvars
ツール
Repository Structure（リポジトリ構造）
- カスタムスクリプトは可能な限り使用しない
- エントリーポイントとなるルートモジュールは環境名で表現する
- 静的ファイルはfiles/ディレクトリに配置する
- ヘルパースクリプトはhelpers/ディレクトリに配置する
- locals.tfは必要な場合のみ使用する
- 全てのモジュールにmain.tfを配置する
- 再利用可能モジュール間の相互参照を避ける
- すべてのディレクトリ名とファイル名にはsnake_caseを使用する
- 全てのモジュールにoutputs.tfを配置する
- providers.tfとversions.tfはルートディレクトリのみに配置する
- 全てのモジュールにREADME.mdを配置する
- 再利用可能なモジュールは ./modules/ 配下に配置する
- リソースブロックは原則main.tfに記述し、大きい場合はサービス名でファイル分割する
- テンプレートファイルは*.tftpl形式でtemplates/ディレクトリに配置する
- terraform.tfvars.jsonに変数値を記述する
- 機密情報は必ず暗号化して*.tfvars.jsonに記述する
- 全てのモジュールにvariables.tfを配置する
Module Design（モジュール設計）
- 関連リソースを論理的にまとめ機能単位でカプセル化する
- 単一リソースを包むだけのモジュールは作らない
- モジュール内リソースの参照値は必ずoutputで公開し依存関係を明示する
- モジュール階層を1〜2段階に保ちフラットな継承を維持する