iac-terraform

Infrastructure as Code - Terraform & Terragrunt

開発から本番環境へのデプロイまで、Terraform と Terragrunt を使用した Infrastructure as Code の包括的なガイダンスです。

主なワークフロー

1. 新しいインフラストラクチャの開発

ワークフローの判断ツリー：

Is this reusable across environments/projects?
├─ Yes → Create a Terraform module
│   └─ See "Creating Terraform Modules" below
└─ No → Create environment-specific configuration
    └─ See "Environment Configuration" below

Terraform モジュールの作成

再利用可能なインフラストラクチャを構築する場合：

1. スクリプトで新しいモジュールをスキャフォールディングします：

python3 scripts/init_module.py my-module-name

これにより、次のものが自動的に作成されます：

• 標準的なモジュールのファイル構成
• 適切にフォーマットされたテンプレートファイル
• examples ディレクトリ
• ドキュメントを含む README

2. モジュールのテンプレート構成を使用します：

   • 完全な構成については assets/templates/MODULE_TEMPLATE.md を参照してください
   • 必須ファイル：main.tf、variables.tf、outputs.tf、versions.tf、README.md
   • 推奨：動作する例を含む examples/ ディレクトリ

3. モジュールのベストプラクティスに従います：

   • 単一責任 — 1 つのモジュールにつき 1 つの目的
   • オプション変数には適切なデフォルト値を設定
   • すべての変数と出力に完全な説明を記載
   • validation ブロックを使用して入力を検証
   • 機密値には sensitive = true を設定

4. モジュールを検証します：

python3 scripts/validate_module.py /path/to/module

次の項目を確認します：

• 必須ファイルが存在する
• 変数に説明と型が設定されている
• 出力に説明が設定されている
• README が存在し、内容が完全である
• 命名規則に従っている
• 機密値が適切にマークされている

4. モジュールをテストします：

cd examples/complete
terraform init
terraform plan

5. モジュールをドキュメント化します：
   • terraform-docs を使用して自動生成します：terraform-docs markdown . > README.md
   • 使用例を含めます
   • すべての入力と出力を記載します

主なモジュールパターン：

以下については、references/best_practices.md の「Module Design」セクションを参照してください：

• 組み合わせ可能な設計パターン
• 変数の整理
• 出力の設計
• モジュールのバージョン管理戦略

環境設定

環境固有のインフラストラクチャの場合：

1. 環境ごとに構成します：

environments/
├── dev/
├── staging/
└── prod/

2. 一貫性のあるファイル構成を使用します：

environment/
├── main.tf           # Resource definitions
├── variables.tf      # Variable declarations
├── terraform.tfvars  # Default values (committed)
├── secrets.auto.tfvars  # Sensitive values (.gitignore)
├── backend.tf        # State configuration
├── outputs.tf        # Output values
└── versions.tf       # Version constraints

3. モジュールを参照します：

module "vpc" {
  source = "git::https://github.com/company/terraform-modules.git//vpc?ref=v1.2.0"
  
  name        = "${var.environment}-vpc"
  vpc_cidr    = var.vpc_cidr
  environment = var.environment
}

2. State の管理と確認

State を確認するタイミング：

• 大規模な変更の前
• ドリフトの調査
• リソースの問題のデバッグ
• インフラストラクチャの監査

State を確認し、健全性をチェックします：

# List all managed resources
terraform state list

# Show detailed state for a specific resource
terraform state show <resource_address>

# Show full state summary (all resources, outputs, providers)
terraform show

ドリフトをチェックします：

# Exit code 0 = no changes, 1 = error, 2 = drift detected
terraform plan -detailed-exitcode

State の操作：

# List all resources
terraform state list

# Show specific resource
terraform state show aws_instance.web

# Remove from state (doesn't destroy)
terraform state rm aws_instance.web

# Move/rename resource
terraform state mv aws_instance.web aws_instance.web_server

# Import existing resource
terraform import aws_instance.web i-1234567890abcdef0

State のベストプラクティス： 以下については、references/best_practices.md の「State Management」セクションを参照してください：

• リモートバックエンドの設定（S3 + DynamoDB）
• State ファイルの構成戦略
• 暗号化とセキュリティ
• バックアップと復旧の手順

3. 標準的な Terraform ワークフロー

# 1. Initialize (first time or after module changes)
terraform init

# 2. Format code
terraform fmt -recursive

# 3. Validate syntax
terraform validate

# 4. Plan changes (always review!)
terraform plan -out=tfplan

# 5. Apply changes
terraform apply tfplan

# 6. Verify outputs
terraform output

Terragrunt を使用する場合：

# Run for single module
terragrunt plan
terragrunt apply

# Run for all modules in directory tree
terragrunt run-all plan
terragrunt run-all apply

4. 問題のトラブルシューティング

エラーが発生した場合：

1. エラーメッセージ全体を読みます — 詳細を見落とさないでください

2. 次の内容を扱う references/troubleshooting.md を参照します：

   • State ロックエラー
   • State のドリフト／破損
   • プロバイダーの認証失敗
   • リソースエラー（既存リソース、依存関係のエラー、タイムアウト）
   • モジュールソースの問題
   • Terragrunt 固有の問題（依存関係の循環、フック）
   • パフォーマンスの問題

3. 必要に応じてデバッグログを有効にします：

export TF_LOG=DEBUG
export TF_LOG_PATH=terraform-debug.log
terraform plan

4. 問題を切り分けます：

# Test specific resource
terraform plan -target=aws_instance.web
terraform apply -target=aws_instance.web

5. よくある簡単な修正方法：

State がロックされている場合（詳しい解決ガイド：references/troubleshooting.md → State Lock Error）：

# Verify no one else running, then:
terraform force-unlock <lock-id>

プロバイダーキャッシュの問題：

rm -rf .terraform
terraform init -upgrade

モジュールキャッシュの問題：

rm -rf .terraform/modules
terraform init

5. コードレビューと品質

コミットする前に：

1. コードをフォーマットします：

terraform fmt -recursive

2. 構文を検証します：

terraform validate

3. tflint で lint を実行します：

tflint --module

4. checkov でセキュリティスキャンを実行します：

checkov -d .

5. モジュールを検証します：

python3 scripts/validate_module.py modules/vpc

6. ドキュメントを生成します：

terraform-docs markdown modules/vpc > modules/vpc/README.md

レビューチェックリスト：

• すべての変数に説明がある
• 機密値が機密としてマークされている
• 出力に説明がある
• リソースが命名規則に従っている
• ハードコードされた値がない（変数を使用する）
• README が完全で最新である
• examples ディレクトリが存在し、動作する
• バージョン制約が指定されている
• セキュリティのベストプラクティスに従っている

包括的なガイドラインについては、references/best_practices.md を参照してください。

Terragrunt のパターン

プロジェクト構成

terragrunt-project/
├── terragrunt.hcl              # Root config
├── account.hcl                 # Account-level vars
├── region.hcl                  # Region-level vars
└── environments/
    ├── dev/
    │   ├── env.hcl            # Environment vars
    │   └── us-east-1/
    │       ├── vpc/
    │       │   └── terragrunt.hcl
    │       └── eks/
    │           └── terragrunt.hcl
    └── prod/
        └── us-east-1/
            ├── vpc/
            └── eks/

依存関係の管理

# In eks/terragrunt.hcl
dependency "vpc" {
  config_path = "../vpc"
  
  # Mock outputs for plan/validate
  mock_outputs = {
    vpc_id         = "vpc-mock"
    subnet_ids     = ["subnet-mock"]
  }
  mock_outputs_allowed_terraform_commands = ["validate", "plan"]
}

inputs = {
  vpc_id     = dependency.vpc.outputs.vpc_id
  subnet_ids = dependency.vpc.outputs.private_subnet_ids
}

一般的なパターン

Terragrunt の完全な設定テンプレートについては、assets/templates/MODULE_TEMPLATE.md を参照してください。以下が含まれます。

• プロバイダー生成を含むルートの terragrunt.hcl
• リモートステートの設定
• モジュールレベルの terragrunt.hcl のパターン
• 依存関係の処理

参考ドキュメント

• references/best_practices.md — プロジェクト構成、ステート管理、モジュール設計、セキュリティ、CI/CD との統合
• references/troubleshooting.md — ステートロックエラー、ドリフト、プロバイダーの問題、リソースエラー、Terragrunt 固有の問題
• references/cost_optimization.md — 適切なサイジング、Spot/RI 戦略、ストレージの最適化、コストタグ付け、マルチクラウド

CI/CD ワークフロー

assets/workflows/ にすぐに使えるテンプレートがあります。

テンプレート	プラットフォーム	機能
github-actions-terraform.yml	GitHub Actions	検証、TFLint、Checkov、PR での plan、main での apply、OIDC
github-actions-terragrunt.yml	GitHub Actions	変更されたモジュールの検出、並列プランニング、依存関係を考慮した apply
gitlab-ci-terraform.yml	GitLab CI	マルチステージパイプライン、アーティファクト管理、手動承認ゲート

スクリプト

スクリプト	目的	使用方法
init_module.py	標準構成で新しいモジュールを作成する	python3 scripts/init_module.py <name> [--path ./modules] [--json]
validate_module.py	ベストプラクティスに照らしてモジュールを検証する	python3 scripts/validate_module.py <path>

アセット

• templates/MODULE_TEMPLATE.md — ファイル構成、例、Terragrunt 設定を含む完全なモジュールテンプレート

クイックリファレンス

基本的なコマンド

# Initialize
terraform init
terraform init -upgrade  # Update providers

# Validate
terraform validate
terraform fmt -recursive

# Plan
terraform plan
terraform plan -out=tfplan

# Apply
terraform apply
terraform apply tfplan
terraform apply -auto-approve  # CI/CD only

# State
terraform state list
terraform state show <resource>
terraform state rm <resource>
terraform state mv <old> <new>

# Import
terraform import <resource_address> <resource_id>

# Destroy
terraform destroy
terraform destroy -target=<resource>

# Outputs
terraform output
terraform output <output_name>

Terragrunt のコマンド

# Single module
terragrunt init
terragrunt plan
terragrunt apply

# All modules
terragrunt run-all plan
terragrunt run-all apply
terragrunt run-all destroy

# With specific modules
terragrunt run-all apply --terragrunt-include-dir vpc --terragrunt-include-dir eks