Terraform Apply失敗パターンの自動分類と学習型レビューチェックリスト生成による再発防止システムの構築

1. Terraform Apply失敗パターンの自動分類と 学習型レビューチェックリスト生成による再発防止システムの構築 2025/02/28 AI実装勉強会第56回（旧機械学習の社会実装勉強会） 今津快斗
2. 目次 2 1 背景と課題 2 施策1: 必要なAPIの洗い出し 3 施策2: PRレビュー自動学習 4 全体像 5 まとめと今後の展望
3. 目次 3 1 背景と課題 2 施策1: 必要なAPIの洗い出し 3 施策2: PRレビュー自動学習 4 全体像 5 まとめと今後の展望
4. Terraform Applyとは 4 コード作成 （.tfファイル） → terraform plan （差分確認） → terraform apply （実行） → インフラ反映 （AWS/GCP等） • terraform plan ： 「何が変わるか」を事前に確認 • terraform apply ： 実際にクラウドにリソースを作成・変更する チーム開発では、PRマージ → CI/CD経由で自動的にapplyが実行される Terraform：インフラをコードで管理するツール（Infrastructure as Code） planが通っても、applyで失敗することがある！ terraform plan terraform apply
5. なぜ terraform plan では検知できないのか 5 例: Google Cloud SQLを作る場合 resource "google_sql_database_instance" "main" { name = "my-database" database_version = "POSTGRES_15" region = "asia-northeast1" } plan結果: Plan: 1 to add → 問題なし！✓ apply結果: Error 403: Cloud SQL Admin API has not been used in project or it is disabled. → API未有効化で失敗！ ↑Terraformの構文チェック＋差分計算のみ • そもそもAPIが有効か • 権限があるのか
6. 背景と実態 調査結果 過去の失敗を網羅的に分析 terraform planは成功するのにapplyで失敗する ケースが多い ✘ 問題 同じ種類のエラーが繰り返し発生していた 事前に防げるはずの失敗が、何度も繰り返されている 6 背景 GCPリソースの管理PRでapplyの失敗が相次いだ PR35件のうち、15件失敗（延べ27回）
7. 解決すべき2つの課題 7 課題1: 必要なAPIの自動洗い出し • 失敗原因の約40%がAPI未有効化 • 変更に対して必要なAPIが分からない • 開発者が毎回ドキュメントを調べるのは面倒 課題2: 同じ失敗パターンの繰り返し防止 • 過去の失敗知見がチームに共有されていない • レビュー時に過去の失敗を参照する仕組みがない 必要なAPIを事前に把握 失敗パターンDB
8. 目次 8 1 背景と課題 2 施策1: 必要なAPIの洗い出し 3 施策2: PRレビュー自動学習 4 全体像 5 まとめと今後の展望
9. 施策1: 必要なAPIの洗い出し 9 開発者がTerraformコードを編集 ↓ git commit 実行 ↓ pre-commitフックが起動 ↓ gcp_check_required_apis.sh 実行 ↓ 変更された.tfファイルを解析 ↓ 必要なAPIを一覧表示 + gcloud services enable コマンドも提示 ポイント: • GCPのAPIを実際に叩かない（認証情報不要） • Terraformコードの静的解析のみ • PR作成前に必要なAPIが分かる
10. 静的解析スクリプトの仕組み 10 Step 1: リソース抽出 .tfファイルからgoogle_*リソースを抽出 → google_sql_database_instance → google_compute_network → google_service_ networking_connection Step 2: API変換 抽出したリソースタイプを、 gcp_resource_api_mapping.jsonを用いて 対応するGCP APIに変換 google_sql_database_instance → sqladmin.googleapis.com google_compute_network → compute.googleapis.com google_service_networking_connection → servicenetworking.googleapis.com Step 3: 結果を表示 このPRで必要なGCP APIの一覧を表示 Required APIs: - sqladmin.googleapis.com - compute.googleapis.com - servicenetworking.googleapis.com gcloud services enable コマンドを 自動生成 To enable: gcloud services enable ¥ sqladmin.googleapis.com ¥ compute.googleapis.com ¥ servicenetworking.googleapis.com 新しいリソースが見つかった場合は、警告を表示 開発者がPR作成前にAPIを有効化
11. pre-commitフックへの統合 11 - repo: local hooks: - id: check-gcp-required-apis name: Check GCP required APIs entry: ./scripts/gcp_check_required_apis.sh language: script files: 'gcp/.*¥.tf$' pass_filenames: false .pre-commit-config.yaml git commit 実行 ↓ pre-commitが自動起動 ↓ gcp/*.tf に変更あり？ ↓ gcp_check_required_apis.sh 実行 ↓ 必要なAPIを表示 （コミットはブロックしない） • gcp/配下の.tfファイルが変更された時のみ実行 • コミットはブロックしない（情報提供のみ） • 開発者は表示されたAPIを事前に有効化できる
12. 施策1 まとめ 12 成果 • Apply失敗の最大原因（約40%）を事前に検知可能に • 認証情報不要の静的解析（CIでも安全に実行可能） • リソースタイプのマッピングを整備 導入ファイル • scripts/gcp_check_required_apis.sh （APIチェックスクリプト） • scripts/gcp_resource_api_mapping.json （マッピングテーブル） • .pre-commit-config.yaml （フック設定追加）
13. 目次 13 1 背景と課題 2 施策1: 必要なAPIの洗い出し 3 施策2: PRレビュー自動学習 4 全体像 5 まとめと今後の展望
14. 施策2: PRレビュー自動学習システム 14 コマンド実行
15. エラーパターン抽出（extract_error_patterns.sh） ① 入力データ読み込み failed_prs_*.json （過去の失敗PR一覧） ② PRコメント取得 GitHub API （失敗ログを収集） ③ 正規表現で分類 5カテゴリに自動振り分け 分類先（5カテゴリ） ▪ API未有効化 11件 ▪ IAM権限不足 8件 ▪ 依存関係エラー 5件 ▪ リソース設定エラー 0件 ▪ その他 3件 ④ 頻度・重要度計算 HIGH / MEDIUM / LOW （優先度を自動付与） ⑤ パターンDB出力 error_patterns.json （エラーDBを更新） 過去27件の失敗コメントを自動分析・分類 → 正規表現ベースで人手不要 15
16. エラーパターンDB（error_patterns.json） 16 { "metadata": { "total_comments_analyzed": 27, "generated_at": "2026-xx-xxTxx:xx:xxZ" }, "patterns": [ { "category": "API Enablement", "description": "Required Google APIs not enabled", "frequency": 11, "severity": "HIGH", "error_regex": "API has not been used...|SERVICE_DISABLED", "check_message": "Verify all required Google APIs...", "detection_method": "scripts/gcp_check_required_apis.sh", "examples": [ {“pr”: 123, "api": "compute.googleapis.com", "resource": "Instance"} ], "api_breakdown": [ {"api": "servicenetworking...", "count": 3}, {"api": "sqladmin...", "count": 2} ] } ] } ポイント: • 過去の失敗コメントを5カテゴリに構造化 • 検出用正規表現を保持し、新たな失敗も分類可能 • APIごとに失敗回数を記録 検出用正規表現 CLAUDE.mdのチェック項目文 失敗回数を記録 重要度 カテゴリ
17. チェックリスト自動生成（generate_review_checklist.sh） 17 error_patterns.json （エラーパターンDB） generate_review_checklist.sh （生成スクリプト） CLAUDE.md （レビュー指示書） ## Terraform PR Review Checklist ### High Priority Checks #### 1. API Enablement（過去11件の失敗） チェック項目: - [ ] Verify all required Google APIs are enabled 過去の失敗API: - servicenetworking.googleapis.com（3件） - sqladmin.googleapis.com（2件） #### 2. IAM Permissions（過去8件の失敗） - [ ] Verify Service Account has necessary IAM roles ### Medium Priority Checks #### 3. Resource Configuration（過去5件の失敗） - [ ] Validate resource configuration values CLAUDE.md（一部）
18. Apply失敗時の自動通知ワークフロー 18 トリガー条件: on: workflow_run: workflows: ["gcp"] types: [completed] jobs: comment-on-failure: runs-on: ubuntu-latest if: github.event.workflow_run.conclusion == 'failure' && github.event.workflow_run.event == 'pull_request’ # Terraformワークフローが完了した時に起動 # 失敗 + PRに紐づく場合のみ実行 投稿されるコメント: Terraform Apply Failed このエラーパターンを学習データに追加しませんか？ 以下のコマンドを実行: ./scripts/extract_error_patterns.sh ./scripts/generate_review_checklist.sh git add scripts/error_patterns.json CLAUDE.md git commit -m "chore: update review checklist" • 失敗を検知して自動的にPRにコメント • 開発者に「学習データ更新」のアクションを促す • コマンドをそのまま実行するだけで更新可能
19. 施策2 まとめ 19 成果 • 過去27件の失敗コメントを5カテゴリに自動分類 • 重要度付きのレビューチェックリストを自動生成 • Apply失敗時の通知→学習→反映のサイクルを構築 導入ファイル • scripts/extract_error_patterns.sh 失敗PRからエラーパターンを自動抽出 • scripts/error_patterns.json エラーパターンDB（学習データの蓄積先） • scripts/generate_review_checklist.sh DBからCLAUDE.md用チェックリストを生成 • .github/workflows/comment-on-apply-failure.yml Apply失敗時にPRへ自動コメント • CLAUDE.md（チェックリスト追記） Claude Codeが参照するレビュー指示書
20. 目次 20 1 背景と課題 2 施策1: 必要なAPIの洗い出し 3 施策2: PRレビュー自動学習 4 全体像 5 まとめと今後の展望
21. 失敗→学習→防止の完全サイクル Terraform Apply 失敗 PRマージ → Apply実行 自動コメント投稿 （失敗を通知） extract_error_patterns.sh （パターン抽出） error_patterns.json （エラーDB更新） generate_review_checklist.sh （チェックリスト生成） CLAUDE.md 更新 PR作成 開発者がAPIを手動で有効化 pre-commitチェック 「◦◦ APIが必要です」 失敗するたびに レビューが賢くなる CLAUDE.md参照 （チェックリスト） PRレビュー （Claude Code） 21
22. 目次 22 1 背景と課題 2 施策1: 必要なAPIの洗い出し 3 施策2: PRレビュー自動学習 4 全体像 5 まとめと今後の展望
23. まとめ 23 成果 • Apply失敗の最大原因 （API未有効化）を事前検知す る仕組みを構築 • 過去の失敗を5カテゴリに自動 分類し、重要度付きチェックリ ストを生成 • 「失敗→学習→防止」のサイク ルを自動化 • 全ツールがGCP APIキー不要（ 静的解析のみ）で安全に動作 技術的なポイント • pre-commitフックによるローカ ルでの事前チェック • GitHub Actionsによる失敗検知 と自動通知 • CLAUDE.md経由でAIレビューに も知見を反映 今後の展望 • マッピングテーブルの自動更新 • CI上でのAPI有効化チェック必須 化 • 他クラウドへの横展開
24. ご清聴ありがとうございました！