セクション1：一般的な落とし穴（「あるあるネタ」）
📊 `buildspec.yml` の設定ミス
ビルド失敗の最も一般的な原因は`buildspec.yml`にあります。構文エラー、フェーズの誤解、パス指定ミスなどが頻発します。以下のグラフは、典型的なエラーの内訳を示しています。
🛡️ IAM権限の迷路
サービスロールの権限不足は、診断が難しいエラーを引き起こします。CodeBuildはS3、ECR、KMSなど多くのサービスと連携するため、最小権限の原則を適用しつつ、必要な権限を正確に付与することが重要です。
⚠️不足
⚠️不足
💥 ビルドステージの崩壊
「ローカルでは動くのに」はCI/CDの常套句です。CodeBuild環境の特性を理解しないと、依存関係の解決、Dockerイメージのアーキテクチャ不一致、ネットワーク問題でビルドが失敗します。
❗ トリガーとアーティファクト
パイプラインが開始しない、またはステージ間でデータが渡らない問題も頻発します。見落としがちな重要ポイントを確認しましょう。
S3バケットのCloudTrailデータイベントが有効になっているか確認してください。これが無効だと、CodePipelineは変更を検知できません。
CodeDeployToECSアクションの入力アーティファクトは3MBのサイズ制限があります。タスク定義ファイルが正しく含まれているか、サイズを超えていないか確認してください。
セクション2：解決困難な問題
📉 断続的な失敗
最も厄介なのが、時々しか発生しない「不安定なビルド」です。これは一時的なネットワーク問題やAPIスロットリングが原因のことが多く、再現が困難です。ビルド安定性の推移を監視することが重要になります。
🔄 CloudFormationロールバックの迷宮
CloudFormationのデプロイが失敗するとロールバックが試みられますが、このロールバック自体が失敗することがあります。外部でのリソース変更やカスタムリソースのタイムアウトが原因で、`UPDATE_ROLLBACK_FAILED`という絶望的な状態に陥ります。
⏱️ パフォーマンスのボトルネック
プロジェクトが大規模になると、ビルド時間が長くなり、開発サイクルが遅延します。キャッシュの活用、並列実行、適切なインスタンスタイプの選択により、パイプラインの実行時間は大幅に短縮可能です。
セクション3：高度なトラブルシューティングツールキット
問題が発生したら、系統的なアプローチで原因を特定します。単純なログ確認から、インタラクティブなデバッグまで、段階的に深掘りしていきましょう。
-
📜
1. CloudWatch Logsの精査
まずは基本です。CodeBuildのビルドログを詳細に確認し、エラーメッセージや失敗したコマンドを特定します。CloudWatch Logs Insightsを使えば、大量のログから効率的に情報を抽出できます。
-
🔍
2. CloudTrailでのAPI監査
権限エラー(`AccessDenied`)が疑われる場合は、CloudTrailでAPI呼び出し履歴を確認します。どのサービスへのどのAPIコールが失敗しているかを正確に把握できます。
-
🔌
3. Session Managerでのライブデバッグ
実行中のビルドコンテナに直接接続し、リアルタイムでデバッグします。環境変数を確認したり、スクリプトを一行ずつ実行したりと、非常に強力な手法です。
-
💻
4. ローカルCodeBuildエージェントでの事前検証
クラウドにプッシュする前に、ローカル環境でビルドをシミュレートします。`buildspec.yml`の構文チェックやスクリプトのデバッグを迅速に行え、コストと時間を節約できます。
セクション4：レジリエントなパイプラインのためのベストプラクティス
Infrastructure as Code (IaC)
パイプラインはCloudFormationやCDKでコードとして管理し、再現性とバージョン管理を徹底します。
シークレット管理
APIキーなどはハードコードせず、Secrets ManagerやParameter Storeで安全に管理します。
冪等性とリトライ
ステージは何度実行しても同じ結果になるように設計し、一時的なエラーにはリトライ処理を実装します。
カスタムビルド環境
依存関係をプリインストールしたカスタムDockerイメージを使い、ビルド時間短縮と環境の一貫性を確保します。