AWS CodePipeline ベストプラクティス

AWS CodePipeline でパイプラインを設計・運用する際のベストプラクティスを、観点ごとに整理したドキュメントです。

目次

1. パイプラインタイプと基本設計
2. ソースとトリガー
3. ステージ構成
4. ビルドとテスト
5. デプロイ戦略
6. 品質ゲートと承認
7. セキュリティ
8. マルチアカウント・マルチリージョン
9. IaC によるパイプライン管理
10. 監視・通知・トラブルシューティング
11. コスト最適化
12. チェックリスト

1. パイプラインタイプと基本設計

V2 パイプラインを使う

新規作成は V2 タイプ を基本とします。V2 でしか使えない主な機能は次のとおりです。

料金体系の違い: V1 はアクティブなパイプライン 1 本あたりの月額課金、V2 はアクション実行時間（分）単位の課金です。実行頻度が低い・短時間のパイプラインが多い場合は V2 が有利になりやすい一方、長時間アクションが多い場合は試算してから選びます。既存 V1 は機能要件に応じて V2 への移行を検討します。

実行モードを用途で選ぶ

責務を小さく保つ

• 1 パイプライン = 1 デプロイ単位（サービス／マイクロサービス） を原則にする
• 巨大なモノリシックパイプラインは失敗時の影響範囲と再実行コストが大きくなる
• パイプライン間の連携が必要なら CodePipeline Invoke アクション で下流パイプラインを起動し、変数やソースリビジョンを引き渡す

2. ソースとトリガー

ソースプロバイダ

• GitHub / GitLab / Bitbucket は CodeConnections（旧 CodeStar Connections）を使う
  • 旧来の OAuth ベースの GitHub (Version 1) アクションや Webhook + 個人アクセストークン方式は避ける
• S3 ソースは バージョニングを有効化 し、EventBridge で起動する（ポーリングは使わない）
• ECR ソースは イメージタグを明示 し、latest への依存を避ける

トリガー設計

• ポーリングではなくイベント駆動（CodeConnections の Webhook、EventBridge）で起動する
• V2 のトリガーフィルタで不要な実行を防ぐ
  • includes / excludes でパスを絞る（例: docs/** の変更ではデプロイしない）
  • 本番リリースは Git タグ（例: v*）トリガー に限定する
  • プルリクエストイベントで検証用パイプラインを起動する
• モノレポではパスフィルタを使ってサービスごとにパイプラインを分ける

# CloudFormation の例（抜粋）
Triggers:
  - ProviderType: CodeStarSourceConnection
    GitConfiguration:
      SourceActionName: Source
      Push:
        - Branches:
            Includes: [main]
          FilePaths:
            Includes: ["services/api/**"]
            Excludes: ["**/*.md"]

3. ステージ構成

推奨する標準構成

Source → Build → Test（ユニット/静的解析/脆弱性スキャン）
       → Deploy-Dev → 統合テスト
       → Deploy-Staging → E2E/負荷テスト → 承認
       → Deploy-Prod（段階的） → デプロイ後検証

設計のポイント

• Build Once, Deploy Many: アーティファクト（コンテナイメージ・zip 等）は 1 回だけビルドし、すべての環境で同じものを使う。環境差分は設定値（パラメータ・環境変数）で吸収する
• 速く失敗させる: 実行時間が短く失敗しやすいチェック（Lint、ユニットテスト）を前段に置く
• 並列化: 互いに依存しないアクションは同じ runOrder にして並列実行する
• 本番に近い環境を経由: 本番直前のステージング環境は構成をできるだけ本番に合わせる
• アクション名・ステージ名は役割が分かる命名にし、通知やログで判別しやすくする

4. ビルドとテスト

CodeBuild

• buildspec.yml は リポジトリ内でバージョン管理 する
• キャッシュ（ローカルキャッシュ / S3 キャッシュ / Docker レイヤーキャッシュ）でビルド時間を短縮する
• コンピュートタイプは過不足なく選ぶ。軽量ジョブには Lambda コンピュート も選択肢
• テストレポート（JUnit / Cucumber など）とカバレッジレポートを CodeBuild のレポート機能に出力する
• バッチビルドで複数のテストを並列化する

Commands アクション

• 簡単なシェルコマンドの実行には Commands アクション を使うと、CodeBuild プロジェクトを別途作らずに済む
• 機密値は Secrets Manager 連携で渡し、コマンド内にハードコードしない
• 複雑な処理・再利用する処理は CodeBuild プロジェクトに切り出す

テスト戦略

• ユニットテスト / 静的解析 / SAST / 依存関係の脆弱性スキャンはビルドステージで実施
• コンテナイメージは Amazon Inspector のスキャンアクション や ECR のスキャン結果で重大な脆弱性があれば止める
• 統合テスト・E2E テストはデプロイ済み環境に対して実行する

5. デプロイ戦略

デプロイ先ごとの推奨アクション

安全なリリース

• 段階的デプロイ: カナリア（例: 10% → 100%）やリニアでトラフィックを移行する
• ウェーブデプロイ: 本番を複数リージョン・複数アカウントに分けて順番に展開し、影響範囲を限定する
• 自動ロールバック:
  • CodeDeploy / Lambda / ECS のデプロイ設定で CloudWatch アラーム連携のロールバックを有効化
  • V2 のステージ条件（on-failure の ROLLBACK）でステージ単位に巻き戻す
• ベイク時間: 本番デプロイ後、一定時間アラームを監視してから次のウェーブへ進む（ステージ条件の CloudWatch アラームルールや待機を利用）
• CloudFormation は 変更セット を作成してから実行し、意図しないリソース置換を事前に検知する

6. 品質ゲートと承認

ステージ条件（V2）を活用する

• 判定ロジックは CodeBuild ルール / Commands ルール でカスタム実装できる

手動承認

• 手動承認は 本当に人の判断が必要な箇所だけ（本番直前など）に置く。乱用するとリードタイムが延びる
• 承認時の確認先（ステージング URL、変更差分、テストレポート）を 承認アクションのコメント・URL に記載 する
• SNS 通知で承認者に知らせ、承認・却下できる IAM 権限を最小限のロールに限定する
• 承認にはタイムアウト（最大 7 日）があることを踏まえて運用を決める

7. セキュリティ

IAM

• パイプラインごとに専用のサービスロール を作り、最小権限にする（サービスロールの共有は避ける）
• アクション単位で別ロール（RoleArn）を指定して権限を分離する
• CodeBuild のサービスロールも同様に最小権限にする
• 人がパイプライン定義を変更できる権限（codepipeline:UpdatePipeline 等）を制限する

シークレット

• 認証情報は Secrets Manager / SSM Parameter Store（SecureString） に格納し、実行時に参照する
• buildspec・パイプライン定義・環境変数（平文）にシークレットを書かない
• 長期のアクセスキーを使わず、IAM ロールで認証する

アーティファクト

• アーティファクトストア（S3）は KMS カスタマーマネージドキーで暗号化
• バケットはパブリックアクセスをブロックし、バケットポリシーで TLS 必須・アクセス元を限定
• ライフサイクルルールで古いアーティファクトを削除する

サプライチェーン

• 依存パッケージは CodeArtifact 等で管理し、取得元を固定する
• コンテナイメージは信頼できるベースイメージを使い、署名・スキャンを組み込む
• 本番デプロイは 保護ブランチ／タグ からのみ実行されるようにする

監査

• CloudTrail でパイプラインの変更・手動承認・手動実行を記録する
• 必要に応じて AWS Config ルールでパイプラインやバケットの設定を継続チェックする

8. マルチアカウント・マルチリージョン

アカウント構成

• ツールアカウント（CI/CD 専用） にパイプラインを置き、Dev / Staging / Prod は別アカウントにする
• デプロイ先アカウントに クロスアカウントロール を用意し、ツールアカウントから AssumeRole する
• アーティファクトバケットの KMS キーポリシー・バケットポリシーでデプロイ先アカウントからの読み取りを許可する

リージョン

• クロスリージョンアクションを使う場合は リージョンごとにアーティファクトストア を設定する
• 本番は 1 リージョンずつウェーブで展開し、問題発生時に被害を局所化する

9. IaC によるパイプライン管理

• パイプライン自体を CloudFormation / AWS CDK / Terraform で定義し、コードレビューを通して変更する
• コンソールでの手動変更は避け、ドリフトを防ぐ
• CDK Pipelines の セルフミューテーション を使えば、パイプライン定義の変更もパイプライン経由で反映できる
• 共通構成はテンプレート化・モジュール化し、チーム間で標準パイプラインを再利用する
• 環境ごとの差分はパラメータで表現し、テンプレート自体は 1 つに保つ

10. 監視・通知・トラブルシューティング

通知

• CodeStar Notifications（通知ルール） または EventBridge で、失敗・承認待ち・成功を Slack / Chatbot / SNS へ通知
• 通知は「失敗」「承認待ち」を優先し、成功通知はノイズにならない範囲に絞る

メトリクス

• CloudWatch のパイプラインメトリクス（実行時間・成功／失敗数）を監視する
• DORA 指標（デプロイ頻度、変更のリードタイム、変更失敗率、復旧時間）の観点でトレンドを追う
• 失敗率や実行時間の悪化にアラームを設定する

トラブルシューティング

• CodeBuild のログは CloudWatch Logs（必要なら S3 にも）に出力し、保持期間を設定する
• 失敗したアクションは ステージの再試行（失敗アクションのみ） で再実行できる
• 実行履歴の保持期間には上限があるため、長期保管が必要な情報は EventBridge 経由で別途保存する

11. コスト最適化

• トリガーフィルタで 不要な実行を減らす（ドキュメント変更などで起動しない）
• SUPERSEDED モードで古い実行を置き換え、無駄なデプロイを減らす
• CodeBuild のキャッシュ・適切なコンピュートサイズで実行時間を短縮する
• 使われなくなったパイプライン・CodeBuild プロジェクト・アーティファクトを定期的に棚卸しする
• V1 / V2 の料金体系を実行パターンに照らして試算し、有利なタイプを選ぶ

12. チェックリスト

設計

• V2 パイプラインを使っている
• 実行モードを用途に応じて選択している
• 1 パイプラインの責務が適切な大きさになっている
• アーティファクトを 1 回だけビルドし、全環境で使い回している

トリガー

• CodeConnections / EventBridge によるイベント駆動になっている
• ブランチ・パス・タグのフィルタで不要な実行を防いでいる

品質・デプロイ

• テスト・脆弱性スキャンがパイプラインに組み込まれている
• 本番は段階的デプロイ（カナリア／Blue/Green／ウェーブ）を採用している
• アラーム連携の自動ロールバックが有効になっている
• 手動承認は必要最小限で、確認情報が添付されている

セキュリティ

• パイプライン・アクションごとに最小権限ロールを使っている
• シークレットは Secrets Manager / Parameter Store から参照している
• アーティファクトバケットが KMS で暗号化され、公開がブロックされている
• CI/CD 専用アカウントからクロスアカウントでデプロイしている

運用

• パイプラインを IaC で管理している
• 失敗・承認待ちの通知が届く
• パイプラインのメトリクスを監視している

参考資料

• AWS CodePipeline ユーザーガイド
• CodePipeline のベストプラクティスとユースケース
• パイプラインタイプ（V1 / V2）
• CodePipeline ドキュメント更新履歴
• AWS Well-Architected Framework – DevOps Guidance