terraform-best-practices

Terraform のベストプラクティス

モジュール設計、状態管理、セキュリティ、テスト、マルチ環境デプロイに関するエンタープライズ向けパターンを用いて、本番環境品質の Terraform インフラストラクチャを構築するための専門的なガイダンスです。

このスキルを使用する場面

• チームや組織向けに再利用可能な Terraform モジュールを作成する
• セキュアなリモート状態管理とバックエンド構成を設定する
• マルチ環境インフラストラクチャ（dev/staging/prod）を設計する
• 自動検証を備えたインフラストラクチャ CI/CD パイプラインを実装する
• 複数のチームやプロジェクトにまたがる大規模なインフラストラクチャを管理する
• 手動でのインフラストラクチャ管理から Infrastructure as Code へ移行する
• 既存の Terraform をリファクタリングして保守性を高める
• インフラストラクチャコードにセキュリティのベストプラクティスを導入する

コアコンセプト

モジュール設計の考え方

• モノリスよりもコンポジション：インフラストラクチャを再利用可能な子モジュールに分割します
• 標準的な構成：main.tf、variables.tf、outputs.tf、versions.tf、README.md
• 型制約：安全性を高めるため、validation ブロックと複合型を使用します
• 動的ブロック：重複を避けながら柔軟な構成を可能にします

状態管理の原則

• リモートバックエンド：チームでの共同作業には S3+DynamoDB または Terraform Cloud を使用します
• 状態の暗号化：保存時と転送時に KMS 暗号化を適用します（必須）
• 状態ロック：DynamoDB を使用して同時変更を防ぎます
• ワークスペース戦略：本番環境にはディレクトリベースを、類似した環境にはワークスペースを使用します

セキュリティの基礎

• シークレット管理：AWS Secrets Manager、HashiCorp Vault を使用します（ハードコードは厳禁）
• 最小権限：環境ごとに IAM ロールを分けます
• セキュリティスキャン：CI/CD で tfsec、Checkov、Terrascan を使用します
• リソースタグ付け：コスト追跡、所有者の特定、コンプライアンス対応を可能にします

テストと検証

• pre-commit フック：コミット前にフォーマット、検証、リントを実行します
• プランのレビュー：適用前に必ずプランを保存してレビューします
• 自動テスト：重要なインフラストラクチャモジュールには Terratest を使用します
• Policy as Code：コンプライアンスを適用するために OPA/Sentinel を使用します

クイックリファレンス

タスク	参照先
モジュール構造、変数、出力、動的ブロック	skills/terraform-best-practices/references/module-design.md
リモートバックエンド、状態の暗号化、ワークスペース戦略	skills/terraform-best-practices/references/state-management.md
変数の優先順位、tfvars、Terragrunt の DRY 構成	skills/terraform-best-practices/references/environment-management.md
シークレット、IAM、スキャンツール、リソースタグ付け	skills/terraform-best-practices/references/security.md
pre-commit フック、Terratest、Policy as Code	skills/terraform-best-practices/references/testing-validation.md
すべての領域を網羅した包括的なチェックリスト	skills/terraform-best-practices/references/best-practices-summary.md

ワークフロー

1. プロジェクトのセットアップ

# Initialize directory structure
mkdir -p {modules,environments/{dev,staging,prod}}

# Set up remote backend (bootstrap S3 + DynamoDB first)
# Configure backend.tf with encryption and locking

2. モジュール開発

# Create module with standard structure
cd modules/my-module
touch main.tf variables.tf outputs.tf versions.tf README.md

# Add validation to variables
# Use complex types for structured inputs
# Document outputs with descriptions

3. セキュリティの強化

# Mark sensitive variables
# Use secret management for credentials
# Configure state encryption
# Set up security scanning in CI/CD

4. テストパイプライン

# Install pre-commit hooks
pre-commit install

# Run validation locally
terraform init
terraform validate
terraform fmt -check

# Security scanning
tfsec .
checkov -d .

# Automated tests (critical modules)
cd tests && go test -v

5. デプロイプロセス

# Plan with output file
terraform plan -out=tfplan

# Review plan thoroughly
terraform show tfplan

# Apply only after approval
terraform apply tfplan

# Verify deployment
terraform output

6. マルチ環境管理

# Use directory-based isolation for production
cd environments/prod
terraform init
terraform workspace list

# Or use Terragrunt for DRY backend config
terragrunt plan

よくある間違い

❌ コードにシークレットをハードコードする → シークレット管理サービスを使用します
❌ 状態ロックを設定しない → 競合を防ぐため、DynamoDB ロックを有効にします
❌ プランのレビューを省略する → 実行プランを必ず保存してレビューします
❌ バージョン制約を設定しない → プロバイダーとモジュールのバージョンを固定します
❌ チームでローカル状態を使用する → 共同作業にはリモートバックエンドを使用します
❌ セキュリティスキャンを実施しない → tfsec/Checkov を CI/CD に統合します
❌ リソースタグが不足している → コストと所有者の追跡のため、すべてのリソースにタグを付けます
❌ 自動テストを実施しない → 重要なモジュールには Terratest を作成します
❌ モノリシックなモジュールを作成する → コンポジション可能な子モジュールに分割します
❌ バックアップ戦略を設けない → 状態バケットで S3 のバージョニングを有効にします

Resources

• Official Docs: https://developer.hashicorp.com/terraform/docs
• Style Guide: https://developer.hashicorp.com/terraform/language/syntax/style
• Module Registry: https://registry.terraform.io/
• Terragrunt: https://terragrunt.gruntwork.io/
• Terratest: https://terratest.gruntwork.io/
• tfsec: https://aquasecurity.github.io/tfsec/
• Checkov: https://www.checkov.io/
• Best Practices: https://www.terraform-best-practices.com/
• AWS Provider: https://registry.terraform.io/providers/hashicorp/aws/latest/docs