deployment-pipeline-design

デプロイパイプラインの設計

承認ゲートを備えたマルチステージ CI/CD パイプラインのアーキテクチャパターン、デプロイ戦略、および環境昇格ワークフロー。

目的

適切なステージ構成、自動化された品質ゲート、段階的デリバリー戦略を通じて、スピードと安全性のバランスを取る、堅牢で安全なデプロイパイプラインを設計します。このスキルは、パイプラインアーキテクチャの構造設計と、信頼性の高い本番デプロイのための運用パターンの両方を扱います。

入力 / 出力

提供するもの

• アプリケーションの種類: 言語/ランタイム、コンテナ化またはベアメタル、モノリスまたはマイクロサービス
• デプロイ先: Kubernetes、ECS、VM、サーバーレス、または platform-as-a-service
• 環境トポロジ: 環境数 (dev/staging/prod)、リージョン構成、エアギャップ要件
• ロールアウト要件: 許容できるダウンタイム、ロールバック SLA、トラフィック分割のニーズ、カナリア vs ブルーグリーンの選好
• ゲートの制約: 承認チーム、必要なテストカバレッジしきい値、コンプライアンススキャン (SAST、DAST、SCA)
• 監視スタック: 自動昇格の判断に使用する Prometheus、Datadog、CloudWatch、またはその他のメトリクスソース

このスキルが生成するもの

• パイプライン構成: ステージ定義、ジョブの依存関係、並列性、キャッシュ戦略
• デプロイ戦略: 注釈付き構成 (カナリアの重み、ブルーグリーンの切り替え、ローリングパラメータ) を伴う、選択されたロールアウトパターン
• ヘルスチェックの設定: 浅い vs 深いレディネスプローブ、デプロイ後のスモークテストスクリプト
• ゲート定義: 自動メトリクスしきい値と手動承認ワークフロー
• ロールバック計画: 自動ロールバックトリガーと手動ランブックの手順

使用する場面

• 新規サービスまたはプラットフォーム移行のための CI/CD アーキテクチャを設計する
• 環境間のデプロイゲートを実装する
• 必須のセキュリティスキャンを伴うマルチ環境パイプラインを構成する
• カナリアまたはブルーグリーン戦略による段階的デリバリーを確立する
• ステージは成功するが本番の動作が正しくないパイプラインをデバッグする
• メトリクス悪化時の自動ロールバックによって平均復旧時間を短縮する

詳細なパターンと実例

詳細なパターンのドキュメントは references/details.md にあります。上記のナビゲーション階層では不十分な場合は、そのファイルを参照してください。

トラブルシューティング

パイプラインではヘルスチェックが成功するが、本番でサービスが異常になる

パイプラインのヘルスチェックが、データベースに接続できない場合でも 200 を返す浅い /ping エンドポイントにアクセスしています。実際の依存関係を検証する深いレディネスチェックを使用してください (上記のヘルスチェックのセクションを参照)。

カナリアデプロイが 100% に昇格しない

Argo Rollouts が自動昇格するには、有効な AnalysisTemplate が必要です。Prometheus クエリがデータを返さない場合 (たとえばメトリクス名が変更された場合)、分析は不確定なままで昇格が停滞します。ロールアウトがハングするのではなく早期に失敗するように、inconclusiveLimit を追加してください:

spec:
  metrics:
  - name: error-rate
    failureCondition: "result[0] > 0.05"
    inconclusiveLimit: 2   # fail after 2 inconclusive results, not hang indefinitely
    provider:
      prometheus:
        query: |
          sum(rate(http_requests_total{status=~"5.."}[2m]))
          / sum(rate(http_requests_total[2m]))

ステージングのデプロイは成功するが、本番ジョブが開始しない

本番環境の保護ルールが構成されていることを確認してください — レビュー担当者の割り当てが欠けていると、承認ゲートが通知なしに無期限に待機します。GitHub Actions では、Settings → Environments → production で Required reviewers が既存のユーザーまたはチームに設定されていることを確認してください。

実行のたびに Docker レイヤーキャッシュが壊れてビルドが遅くなる

依存関係のインストールの前に COPY . . がある場合、ソースファイルの変更が依存関係レイヤーを無効化します。先に依存関係のマニフェストをコピーするように順序を変更してください:

# Good: dependencies cached separately from source code
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

ロールバックしてもデータベースマイグレーションが古いコードに適用されたままになる

マイグレーションのロールバックを伴わないサービスのロールバックは、スキーマ/コードの不一致エラーを引き起こします。少なくとも 1 リリースサイクルの間は、マイグレーションを後方互換 (追加のみ) にしてください。また、undo スクリプトをマイグレーションと一緒にバージョン管理してください:

# migrations/V20240315__add_nullable_column.sql       (forward)
# migrations/V20240315__add_nullable_column.undo.sql  (backward)

古いコードバージョンがすべての環境から完全に退役するまで、破壊的なマイグレーション (DROP COLUMN、ALTER NOT NULL) を実行しないでください。

高度なトピック

プラットフォーム固有のパイプライン設定、マルチリージョンのプロモーションワークフロー、高度な Argo Rollouts パターンについては、以下を参照してください:

• references/advanced-strategies.md — 拡張 YAML の例、プラットフォーム固有の設定（GitHub Actions、GitLab CI、Azure Pipelines）、マルチリージョンのカナリアパターン、データベースマイグレーションのロールバック戦略

関連スキル

• github-actions-templates - GitHub Actions の実装パターンと再利用可能なワークフロー向け
• gitlab-ci-patterns - GitLab CI/CD パイプラインの実装向け
• secrets-management - CI/CD パイプラインにおけるシークレットの取り扱い向け