🌵

【terraform】GoogleStyleGuide咀嚼

2024/01/04に公開

AWS

概要

GoogleStyleGuide(terraform)
terrafomrを使用する為のベストプラクティス（Google公式）への自己解釈
特に留意するべきことを抜粋(意訳アリ・詳細はそれぞれリンク参照)

🪨スタイルと構造に関する一般的なガイドライン

🌵標準のモジュール構造に従う

terraform実行ディレクトリにはmain.tfを起因として、モジュールを呼び出す
モジュール配備ディレクトリにはREADME.mdを必ず配置
terraform実行ディレクトリにはexamples/ディレクトリを作成し、
サンプルコードをとREADME.mdを配置
モジュールの*.tfは目的別に分け、長大化を避ける
モジュールディレクトリにはCHANGELOG.mdを配置し履歴を手書きで残す

🌵命名規則を採用する

リソース名には_を使用する。-を使用しない
参照されるリソースについては名前を簡略化する
リソースタイプに含まれる文言をリソース名に含まない
- aws_s3_bucketというリソース名に s3、bucket というワードは避ける

🌵変数を慎重に使用する

すべての変数を variables.tf で宣言する
単位（MB・GB等）が影響する変数は、単位を変数名に組み込むとメンテナンス性が上がる
必須でないオプショナルな変数は、接頭語に optional などを付与
- requiredの場合は特に明記しないことで差別化を計る
ON・OFFの条件を判定する場合は、正(enable・true)の値を変数名に組み込む
変数名のdescriptionは必須明記
変数の型定義は必ず行う
環境に依存しない変数についてはデフォルト値を設ける
非公開のvalueについては、.gitignoreに含まれるファイルで管理する

🌵出力を公開する

output.tfを使用する際は、仕様についてREADME.mdに明記する
output.tfにて渡す変数は、descriptionを併せて記載する
variablesから、outputには直接変数を渡さないこと（依存関係が崩れる為）

🌵データソースを使用する

データソースにて外部値を参照する場合は、引用するリソースと一緒の箇所に記載する
- 但し、データソースを多く参照する場合については専用のdata.tfを検討する

🌵カスタムスクリプトの使用を制限する

カスタムスクリプトは極力使用しないこと
- terraformの挙動が対応していない場合のみ使用
- カスタムスクリプトはscripts/ディレクトリを作成して配備する
- README.mdに詳細を記載し、メンテナンス性を担保すること

🌵静的ファイルを別のディレクトリに配置する

terraformにて参照する静的ファイルはfiles/ディレクトリ配下に配備する
template関数を使用して参照するファイルはtemplates/ディレクトリ配下に配備する
- templateファイルは拡張子.tftplを使用する

🌵ステートフルリソースを保護する

データベース・ディスクなどのステートフルリソースは削除保護を有効にする

🌵組み込みの書式設定を使用する

terraform　fmtに準拠したコーディングをする(要はterraform fmtを実行しろ)

🌵式の複雑さを制限する

１行のコードに関数を多用しない
- local関数などを使用し、分割をこころがけ可読性をあげる
１行のコードに3項演算子を複数用いない

🌵条件値に count を使用する

条件付きでリソースをインスタンス化するには、count メタ引数を使用する

variable "readers" {
description = "..."
type        = list
default     = []
}

resource "resource_type" "reference_name" {
// Do not create this resource if the list of readers is empty.
count = length(var.readers) == 0 ? 0 : 1
...
}

🌵反復されるリソースに対して for_each を使用する

複数リソースを一括で作成する際は、for_each関数を使用する

🪨再利用可能なモジュール

🌵モジュールで必要な API を有効にする

GCPでterraformを使用する際は、project_servicesリソースを使用してAPIを有効化する

🌵オーナーファイルを含める

すべての共有モジュールにOWNERS ファイルを含める
- GitHub では CODEOWNERSが相当

🌵タグ付きバージョンをリリースする

バージョニングによって互換性を失うリソースについては、メジャーバージョンを固定する

🌵プロバイダやバックエンドを構成しない

共有モジュールでbackendやproviderは指定せず、terraformコマンド実行ディレクトリにて指定する
providerバージョンを共有モジュールで記載する場合は、
required_providersブロックに最低限のバージョンを記載する

🌵複雑なロジックにインラインサブモジュールを使用する

インラインサブモジュールとはモジュール内で更に呼び出す為のモジュールである
- モジュール内は完結に記載できるようサブモジュールを使用するケースがある
- インラインサブモジュールはモジュールからしか呼ばれなく、外部からは呼ばれない作りにする

🪨Terraform のルートモジュール

ルートモジュールとはterraform CLIを実行するディレクトリを指す

🌵各ルートモジュールのリソース数を最小限に抑える

ルートモジュールから呼び出されるリソースは100個未満に抑える

🌵環境固有のサブディレクトリにアプリケーションを分割する

サービスのディレクトリ配下には下記の2つのディレクトリを設ける
- サービスモジュールmodules/
  - 再利用し、複数構築されるリソースはサービスモジュールと呼ぶ（EC2など）
  - 再利用し、環境を跨ぐ（Stage・Prod）リソースは参照モジュールと呼ぶ(ACMなど)
- 環境ディレクトリenvironments/
  - environments/ディレクトリ配下は環境ディレクトリを掘る

🌵環境ディレクトリを使用する

サービスモジュールは共通入力をハードコーディングする
環境毎の固有値は変数化して、ルートモジュールからの値を参照する構成にする
環境ディレクトリ配下に下記ファイルを必須とする
- tfstateを管理するbackend.tf
- サービスモジュールをインスタンス化するmain.tf
terraformの機能である、workspaceは非推奨